Java中應該有什么javadoc？

Question

應該通過javadoc注釋（類，方法，構造函數和字段？或者只有類方法和構造函數？）來記錄什么？ 那有什么約定嗎？

請盡可能在答案中提供相關資源的鏈接。 謝謝

編輯：問題不在於如何通過javadoc進行評論或使用javadoc進行評論是合乎邏輯的。 問題是在任何官方Sun / Oracle文檔中可以找到關於此事的內容（關於編寫javadoc，約定，規范等的指南）。 另外請不要回答有關javadoc評論應該如何的問題，問題是關於應該評論什么，而不是如何評論。

Answer 1

Javadoc用於記錄代碼的公共API。

簡而言之，您需要記錄所有公共和受保護的類，方法，構造函數和字段（因為用戶可以訪問它們）。

您需要描述方法的作用，而不是它是如何做的。 當然，如果實現細節導致有趣的副作用，例如性能特征以及使用限制，那么應該提及這些副作用。

Oracle有關於“ 如何為Javadoc工具編寫Doc注釋 ”的官方指南。

Answer 2

Thilo提到的javadoc的簡單和一般規則以及此處應該如下：

Javadoc指南

通用規則

• 所有公共和受保護的方法都必須有完整的文檔
• 瑣碎的getter和setter免於此規則。 干
  什么，但返回或改變一個
  應記錄getter或setter中的變量。
• 具有非顯而易見的實現的私有方法應該足夠了
  允許其他的文檔
  開發人員調試它們

官方指南可在此處找到： 如何為Javadoc工具編寫Doc注釋

Answer 3

想象一下，將代碼展示給熟悉編程語言的其他人，而不是您的項目。 無論您認為需要解釋哪個部分，因為您正在觀看他的評論，應該記錄下來。

關於程序員的類似問題.SE： 你應該記錄一切還是只記錄大部分內容？