Java 文檔註釋與 Javadoc 完整指南：從寫法到生成 API 文檔

Java 文檔註釋（Javadoc）規範與實戰

三種註釋對比

文檔註釋結構

/**
 * 類/方法/字段的核心描述（第一句會出現在摘要表中）
 * 
 * 詳細說明：功能、用法、線程安全性、異常情況、使用示例...
 * 
 * @標簽 具體信息
 * @see 相關類/方法鏈接
 * @since 版本
 * @deprecated 棄用說明
 */

常用標簽速查表

完整實戰範例

/**
 * 數組工具類，提供常用數組操作。
 * 

 * 所有方法均為靜態，線程安全，不修改輸入數組。
 * 
 * 
 * @author Li Si
 * @version 1.2.0
 * @since 2.0.0
 */
public final class ArrayUtils {

    /** 私有構造函數，防止實例化 */
    private ArrayUtils() {}

    /**
     * 獲取 int 數組最大值。
     * 
     * @param arr 輸入數組，不可為 null，長度必須 > 0
     * @return 數組最大值
     * @throws IllegalArgumentException 若 arr 為 null 或空數組
     * @see #getMin(int[])
     */
    public static int getMax(int[] arr) {
        if (arr == null || arr.length == 0) {
            throw new IllegalArgumentException("Array must not be null or empty");
        }
        int max = arr[0];
        for (int i = 1; i < arr.length; i++) {
            if (arr[i] > max) max = arr[i];
        }
        return max;
    }

    /**
     * 冒泡排序（升序），原地排序。
     * 
     * @param arr 待排序數組，可為 null（無操作）
     */
    public static void bubbleSort(int[] arr) {
        if (arr == null) return;
        for (int i = 0; i < arr.length - 1; i++) {
            for (int j = 0; j < arr.length - 1 - i; j++) {
                if (arr[j] > arr[j + 1]) {
                    int tmp = arr[j];
                    arr[j] = arr[j + 1];
                    arr[j + 1] = tmp;
                }
            }
        }
    }
}

生成文檔命令

# 基礎生成
javadoc -d docs -sourcepath src -subpackages com.example -author -version -encoding UTF-8

# 參數詳解
-d docs           # 輸出目錄
-sourcepath src   # 源碼根路徑
-subpackages pkg  # 遞歸處理包
-author           # 包含 @author
-version          # 包含 @version
-encoding UTF-8   # 源碼編碼
-windowtitle "My API"  # 瀏覽器標題
-doctitle "<h1>My Project API</h1>"  # 首頁標題
-header "<b>My Project</b>"      # 頁面頂部
-footer "© 2024 My Corp"       # 頁面底部
-link https://docs.oracle.com/javase/8/docs/api/  # 鏈接 JDK API

生成效果預覽

• index.html：首頁，包含包列表、類列表
• com/example/ArrayUtils.html：類詳情頁，含方法摘要表、詳細說明、繼承樹
• package-summary.html：包級說明（需 package-info.java）
• allclasses-frame.html：全類列表框架

最佳實踐

1. 公共 API 必須 100% 覆蓋：類、公共方法、公共常量、枚舉值
2. 第一句話要話說完整：Javadoc 摘要表只顯示第一句
3. 參數/返回值/異常全覆蓋：無參數也寫 @param 說明「無參數」
4. 善用 {@link} 建立導航網：讓文檔像維基百科一樣可跳轉
5. CI/CD 集成：每次構建自動生成、發布至內部文檔站
6. package-info.java **補充包級架構說明**

常見問題

優質的 Javadoc 是團隊協作、對外交付、新人上手的「說明書」。養成「寫代碼即寫文檔」習慣，讓文檔與代碼同步演進，是專業工程師的基本素養。