Java 提供三種註解：單行 //、多行 /* */、文檔註解 /** */。文檔註解可被 javadoc 工具解析生成專業 HTML API 文檔（如 JDK 官方文檔）。本文詳細解析文檔註解語法、標準標籤、命令選項與最佳實踐。

文檔註解基本結構

/**
 * 類/方法/欄位的簡短描述（第一句話，以句號結束）。
 * <p>
 * 詳細說明，可包含 HTML 標籤（<br>、<code>、<pre>、<ul> 等）。
 *
 * @param 參數名 參數說明
 * @return 返回值說明
 * @exception 異常類 觸發條件說明
 * @see 相關類/方法 參考連結
 * @author 作者名
 * @since 版本號
 * @version 版本號
 * @deprecated 棄用說明
 */
public class Example { ... }

三大內容區塊

1. 摘要：第一句話（含句號），顯示於類/成員摘要表
2. 詳細描述：<p> 之後的內容，顯示於詳細說明區
3. 標籤區：@tag 開頭的結構化元數據

關鍵規則：文檔註解必須緊貼所描述的類/介面/方法/欄位之前，中間不可有 import、package 或其他程式碼。

標準標籤完整參考

@see 參考語法詳解

@see 全限定類名                    // 類連結
@see 全限定類名#方法名(參數類型)      // 方法連結
@see #方法名(參數類型)              // 本類方法連結
@see #欄位名                        // 本類欄位連結
@see <a href="URL">連結文字</a>      // 外部連結

類名若在 import 中或屬於 java.lang，可用簡短名；否則需全限定名。

HTML 標籤在文檔註解中的使用

• <p> 段落分隔（必要，否則內容合併為單段）
• <br> 強制換行
• <code> / <pre> 程式碼片段（<pre> 保留縮排）
• <ul><li> 列表、<table> 表格
• {@link 參考} 行內連結：{@link String#length()}
• {@code 文字} 等寬字體：{@code null}
• {@literal 文字} 不解析 HTML：{@literal }
• {@value 全限定類名#常數名} 插入常數值

javadoc 命令選項速查

javadoc [options] [packagenames] [sourcefiles]

常用選項:
  -d <dir>              輸出目錄（必須預先存在）
  -sourcepath <path>   源碼路徑
  -subpackages <pkg>  遞迴處理子套件
  -public               僅 public 類/成員（預設）
  -protected            public + protected
  -package              public + protected + package-private
  -private              所有成員
  -author               包含 @author
  -version              包含 @version
  -splitindex           依字母分割索引檔
  -windowtitle <text>  瀏覽器標題
  -doctitle <html>     文檔首頁標題
  -header <html>       頁首
  -footer <html>       頁尾
  -link <url>          連結外部文檔（如 JDK API）
  -linkoffline <url> <pkg-list> 離線連結外部文檔
  -encoding UTF-8       源碼編碼
  -docencoding UTF-8    輸出編碼
  -charset UTF-8        兩者同時設定

實戰範例：生成專案文檔

# 專案根目錄執行
javadoc -d docs \
        -sourcepath src/main/java \
        -subpackages com.mycompany \
        -author -version \
        -encoding UTF-8 -docencoding UTF-8 \
        -link https://docs.oracle.com/javase/8/docs/api/ \
        -windowtitle "MyProject API" \
        -doctitle "
MyProject API 文檔
" \
        -header "MyProject
版本 1.0" \
        -footer "Copyright © 2024"

Maven/Gradle 整合

<!-- Maven: pom.xml -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.5.0</version>
  <configuration>
    <encoding>UTF-8</encoding>
    <docencoding>UTF-8</docencoding>
    <charset>UTF-8</charset>
    <links>
      <link>https://docs.oracle.com/javase/8/docs/api/</link>
    </links>
  </configuration>
</plugin>

# 生成: mvn javadoc:javadoc

最佳實踐清單

1. 所有 public/protected 類、介面、方法、欄位必須有文檔註解
2. 摘要第一句話以動詞開頭（如「返回...」、「判斷...」、「設定...」）
3. @param、@return、@throws 三大標籤缺一不可
4. 善用 {@link} 建立交叉參考網絡，而非純文字引用
5. 棄用 API 必加 @deprecated 與 {@link} 指向替代方案
6. CI 流程整合 javadoc 檢查（-Xdoclint:all），阻擋缺漏註解合併
7. 定期發布版本化文檔至內部 Nexus/GitHub Pages，供團隊檢索

良好的 API 文檔是框架/庫可用性的關鍵。養成「寫代碼即寫文檔」的習慣，讓 Javadoc 成為專案的活體說明書。