Java中應該有什麼javadoc？

應該由javadoc註釋（類，方法，構造函數和字段？或只有類方法和構造函數？）記錄什麼？有關於此的任何約定嗎？Java中應該有什麼javadoc？

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

編輯：這個問題不是關於它通常如何做，或與javadoc評論是合乎邏輯的。問題是在任何官方的Sun/Oracle文檔（關於編寫javadoc，約定，規範等的準則）中可以找到關於此事的信息。另外請不要回答關於javadoc評論應該如何的問題，這個問題具體是關於應該評論什麼，而不是如何評論。

2010-10-15 drasto

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

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

2010-10-15 02:20:45 Thilo

請看到問題的編輯。我知道它應該是什麼樣子，我只需要知道是否有一些公約，官方指導方針或規則應該評論什麼。 – drasto 2010-10-15 02:28:31

想象一下，將代碼展示給熟悉編程語言的其他人，而不是您的項目。無論你在觀看他審閱時需要解釋的部分，都應該記錄下來。

上programmers.SE

類似的問題：由蒂洛，也從here提到的應該是作爲javadoc的Should you document everything or just most?

2010-10-15 02:24:34

如果你正在談論代碼審查或者讓一個新的程序員加快代碼庫速度，我不認爲這是JavaDoc的目的。 – Thilo 2010-10-15 02:27:42

請參閱我的問題的編輯。謝謝。 – drasto 2010-10-15 02:29:09

@Thilo這只是一個幫助人們決定他們什麼時候記錄「足夠」的例子，但編輯聽起來像是在問一些不同的東西 – 2010-10-15 02:32:25

簡單和一般規則如下：

的Javadoc的準則

一般規則

所有公共和受保護的方法都必須具有完整的文檔

微不足道的getter和setter被豁免遵守此規則。做
任何東西，但返回或更改
變量吸氣劑或設置者應該記錄。

與非顯而易見實現私有方法應該有足夠的
文件，以允許其他
開發人員進行調試

2010-10-15 03:06:44 YoK

吸氣劑和吸附劑也有優點。他們可以返回還是接受null？這個屬性是什麼意思？它如何影響對象或類的行爲？ – 2010-10-15 14:29:54

回答