Java - 將javadoc與方法註釋一起使用的慣例？

我有以下方法：Java - 將javadoc與方法註釋一起使用的慣例？

@Override 
    public boolean myMethod() 
    { 
     // do stuff 
    }

如果我想添加一個javadoc這種方法，有沒有關於如何做到這一點與具有@Override註釋（或其他任何註解）沿着任何約定？

我問的原因是因爲我讀過javadoc註釋必須直接在方法之前（兩者之間沒有新行），並且我不確定是否將@avidoc註釋直接放在@Override註釋之上會亂七八糟事情了。

這是傳統的做法嗎？這是否工作？

/** 
    * This is my method's javadoc comment. 
    */ 
    @Override 
    public boolean myMethod() 
    { 
     // do stuff 
    }

來源

2012-03-25 Tim

總有一個人。我想知道公約是什麼，不只是它是否有效。 – Tim 2012-03-25 21:03:07

是的，這種方式是正確的方式，我沒有看到相反的方向。是的，這種方式是有效的。沒有嘗試另一種方式。

/** 
    * This is my method's javadoc comment. 
    */ 
    @Override 
    public boolean myMethod() 
    { 
     // do stuff 
    }

但基本上我通常不會Javadoc註釋實現接口時，添加到覆蓋另一種方法一種方法，尤其是。標籤@inheritDoc在這裏很有幫助，可以毫不費力地分發文檔。但是，這是特定於此示例，您也可以添加其他註釋。

來源

2012-03-25 20:06:56 Markus

我不同意重寫的方法不應該記錄。這對於已實現的接口方法可能是正確的，但重寫的類方法的文檔可以說明方法行爲中發生了什麼變化。當然，通過使用'@ inheritDoc' Javadoc-tag可以避免很多輸入，但IMO文檔不應該在重寫的方法上省略。 – buc 2012-03-25 20:15:31

基本上我同意你的看法，因此稍微更新了我的答案。但我認爲javadoc是用於記錄**一種方法的功能，而不是**如何完成。改變方式如何完成是非常好的，但是這種改變不應該違反超類定義的合約，這會導致需要改變javadoc。這就是爲什麼我認爲爲每種方法編寫javadoc並不是必需的。 – Markus 2012-03-25 20:25:05

是的，它會正常工作。例如，在來自openjdk的source code of java.lang.String中，他們在@Deprecated註釋之上使用javadoc。

來源

2012-03-25 20:08:39 Tudor

Java - 將javadoc與方法註釋一起使用的慣例？

回答

相關問題