Javadoc 標籤完整指南：從 @author 到 {@link} 的實戰用法

Javadoc 註解由「描述性文字」與「標籤」組成，可標註類別、介面、建構子、欄位、方法。本文以 Person.java 實例，逐一拆解常用標籤在生成文件中的呈現效果。

基本結構

/**
 * 描述文字（可含 HTML 標籤）
 * @標籤 參數
 * {@內嵌標籤 參數}
 */
public class Person { ... }

標籤分類與實例

類別層級標籤

方法/建構子標籤

欄位/常數標籤

• {@value}：內嵌標籤，輸出常數值。/** 男性，值為{@value} */ public static final int MALE = 1; → 文件顯示「男性，值為 1」

內嵌連結標籤 {@link}

可嵌入描述文字中，生成超連結：

@param sex int 性別，有效值是{@link #MALE 男性}和{@link #FEMALE}

支援跨類別：{@link javadoc.tool.Car#drive(int)}

@see 進階用法

• 同類別成員：@see #getSex()、@see #MALE（前綴 #）
• 其他類別：@see javadoc.tool.Car（需 import 或全名）
• 多載方法區分：@see Car#drive(int,int) vs @see Car#drive(int)

文件呈現差異：摘要 vs 詳細說明

• 摘要列表：只顯示第一句描述（以句號分隔）。
• 詳細區塊：顯示完整描述、所有標籤資訊、連結。

常用標籤速查表

較少用但值得知道的標籤

@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、{@code}、{@value arg} — 詳見 官方文件。