- 類/方法/字段的簡要描述（單行）
-
- 詳細描述（可選，多行）
-
- @標籤1 描述1
- @標籤2 描述2
- ... */ 常用標籤（Tags） 標籤 作用 適用範圍 @author 標識作者 類、接口 @version 標識版本號 類、接口 @param 描述方法參數（參數名 + 含義） 方法、構造器 @return 描述返回值含義 非 void 方法 @throws 描述方法可能拋出的異常（含原因） 方法、構造器（檢查型異常） @exception 同 @throws（更側重異常類型説明） 方法、構造器 @see 引用其他類 / 方法（生成交叉鏈接） 類、方法、字段等 @since 標識從哪個版本開始引入 類、方法、字段等 @deprecated 標識已過時（建議替代方案） 類、方法、字段等 {@link} inline 鏈接（在描述中插入其他元素鏈接） 任意描述文本中 {@code} 標記代碼片段（保留格式，不解析標籤） 任意描述文本中 示例
- 類註釋 java 運行 /**
- 計算器工具類，提供基本的加減乘除運算。
-
- 該類所有方法均為靜態方法，無需實例化即可使用。
- 支持整數和浮點數運算，若輸入非法參數（如除數為0），會拋出異常。
-
- @author Alice
- @version 1.0
- @since JDK 1.8 */ public class Calculator { // ... }
- 方法註釋 java 運行 /**
- 計算兩個數的和。
-
- 支持正數、負數和零的加法，結果為兩數之和。
- 示例：
- {@code
- int result = Calculator.add(3, 5); // 結果為 8
- }
-
-
- @param a 第一個加數
- @param b 第二個加數
- @return 兩數之和（int類型）
- @see Calculator#subtract(int, int) 減法運算 */ public static int add(int a, int b) { return a + b; }
- 帶異常的方法註釋 java 運行 /**
- 計算兩個數的商（a / b）。
-
- @param a 被除數
- @param b 除數
- @return 商（double類型）
- @throws ArithmeticException 當除數 b 為 0 時拋出
- @deprecated 該方法精度較低，建議使用 {@link Calculator#dividePrecise(double, double)} */ @Deprecated public static double divide(int a, int b) { if (b == 0) { throw new ArithmeticException("除數不能為0"); } return (double) a / b; } 生成文檔 使用 JDK 自帶的 javadoc 工具生成 HTML 文檔： bash
生成當前目錄下所有 .java 文件的文檔，輸出到 doc 文件夾
javadoc -d doc *.java
僅生成指定類的文檔，幷包含作者和版本信息
javadoc -d doc -author -version Calculator.java 注意事項 文檔註釋應簡潔明瞭，突出核心功能，避免重複代碼邏輯。 標籤後的參數名需與代碼中的參數名一致（否則生成文檔時會警告）。 對於重載方法，需明確區分各方法的差異（如參數不同的場景）。 可使用 HTML 標籤（如
、
、）美化文檔格式，但避免過度複雜。
通過規範的文檔註釋，不僅能幫助團隊成員快速理解代碼，還能生成專業的 API 文檔（類似 Java 官方文檔），是大型項目開發的必備實踐。
