JavaDoc 核心標籤深度解析：@param 與 @see 的正確用法與進階技巧

@param：精準記錄參數契約

基本語法

/**
 * 讀取指定數量的單字
 *
 * @param max 最大讀取單字數，必須為正整數
 * @param encoding 字元編碼，預設 UTF-8
 * @return 實際讀取的單字列表
 * @throws IOException 若檔案讀取失敗
 */
public List<String> readWords(int max, String encoding) throws IOException { ... }

泛型類型參數記錄

/**
 * @param <E> 列表元素類型
 * @param list 待處理列表
 * @param comparator 比較器，不可為 null
 */
public static <E> void sort(List<E> list, Comparator<? super E> comparator) { ... }

最佳實踐

• 每個參數獨立一行，參數名與描述以空格分隔
• 描述包含約束條件 (範圍、非空、預設值)、業務含義
• 建構子同樣需要 @param
• 避免冗餘：@param list 列表 → @param list 待排序的使用者列表，不可為 null

@see：建立文檔知識圖譜

引用格式大全

自訂連結文字 (Label)

/**
 * @see #getName() 取得使用者顯示名稱
 * @see java.util.Map#put(Object, Object) Map 放入鍵值對
 */
public void updateProfile(...) { ... }

產出文檔中將顯示「取得使用者顯示名稱」而非方法名，提升可讀性。

進階應用場景

1. 介面契約文檔化

public interface Cache<K, V> {
    /**
     * 取得快取值
     *
     * @param key 快取鍵，不可為 null
     * @return 對應值，不存在回傳 null
     * @see #put(Object, Object)
     * @see #evict(Object)
     */
    V get(K key);

2. 遷移與棄用指引

/**
 * @deprecated 2.0 版起改用 {@link #calculateTax(Money, TaxRule)}
 * @see #calculateTax(Money, TaxRule)
 */
@Deprecated
public BigDecimal calculateTax(double amount, String ruleCode) { ... }

3. 模式與架構參考

/**
 * 策略模式實作
 * @see "GoF Design Patterns - Strategy"
 * @see com.company.pattern.strategy.PaymentStrategy
 */
public class PaymentProcessor { ... }

工具鏈整合

• IDE 支援：IntelliJ/Eclipse 自動補全 @see 目標、重構時同步更新連結
• 建置驗證：Maven javadoc:javadoc 失敗於斷連結，CI 管道可強制檢查
• 文檔發布：整合至 GitHub Pages / Confluence，建立可搜尋的 API 知識庫

總結

@param 是 API 契約的核心註釋，@see 則編織文檔之間的語義網絡。嚴謹撰寫兩者，配合現代 IDE 與 CI 工具，能將 JavaDoc 從「附屬品」昇級為「活的系統設計文檔」，大幅降低團隊溝通成本與新人上手門檻。