您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 相關知識

撰寫 Javadoc 文件註解完整規範指南

編輯：Java 相關知識

1. Javadoc 取得方式

Javadoc 工具內建於 JDK bin/ 目錄。各版本對應：

Javadoc 1.4 ← Java 2 SDK 1.4
Javadoc 1.3 ← Java 2 SDK 1.3
Javadoc 1.2 ← Java 2 SDK 1.2
Javadoc 1.1 ← JDK 1.1

2. 文件註解核心原則

Java 平台 API 文件源自原始碼中的文件註解。
API 文件是呼叫端與實作間的契約。
除非另有說明，文件應與具體實作無關。
文件需夠詳細，供 JCK (Java Compatibility Kit) 編寫測試案例。

3. 撰寫細則

3.1 第一句話 = 摘要句

每個文件註解的第一句需簡潔完整描述 API 項目，以「句點+空白」結束。若句中含縮寫 (如 e.g.)，需轉義空白：e.g.\ 。

3.2 繼承註解機制

類別覆寫父類方法、介面覆寫父介面方法、類別實作介面方法時，若無文件註解，自動繼承父類/介面註解。
若有自訂註解，則不繼承；產生文件時會標示 Overrides 或 Specified by。

3.3 標記與格式

用途	標記	範例
關鍵字/名稱	`<code>...</code>`	`<code>String</code>`
行內連結	`{@link Class#member}`	節制使用
方法/建構子說明	省略括號	`getName` 而非 `getName()`
簡短敘述	可用片語	「Returns the name」優於「This method returns the name」
人稱	第三人稱	「Gets the name」非「Get the name」
動詞開頭	方法描述以動詞片語起頭	「Returns...」「Sets...」「Throws...」
類別/欄位描述	可省略主詞	「The name of the user」
指代當前實例	用 `this` 不用 `the`	「Sets `this` object's name」

3.4 禁止事項

單純展開 API 名稱當描述（需補充資訊）。
使用 field 一詞易混淆（建議用 member variable）。
拉丁文縮寫 (i.e., e.g. 等)——改用英文說明。

3.5 標籤順序 (Tag Order)

@author (多位依貢獻時間排序)
@version
@param (依方法宣告順序，格式：@param 參數名 描述)
@return (非 void 必寫)
@exception / @throws (依例外類別字母序)
@see (依規定順序：#field, #Constructor, #method, Class, Class#member, package.Class...)
@since
@serial
@deprecated

@param 與 @return (非 void) 為必寫。

4. 範例

/**
 * Returns the current user's display name.
 * <p>
 * If the user has not set a display name, the login name is returned.
 *
 * @return the display name, or login name if display name is not set
 * @since 1.2
 * @see #setDisplayName(String)
 */
public String getDisplayName() { ... }