Javadoc

Javadoc（最初是JavaDoc）是由Sun Microsystems為Java語言（現在由甲骨文公司擁有）創建的文檔生成器，用於從Java源代碼生成HTML格式的API文檔，HTML格式用於增加將相關文檔鏈接在一起的便利性。

Javadoc使用的「doc comments」格式 是記錄Java類的事實上的行業標準。一些IDE，如IntelliJ IDEA、NetBeans和Eclipse，可以自動生成Javadoc HTML。許多文件編輯器幫助用戶生成Javadoc源代碼並使用Javadoc信息作為程序員的內部引用。

Javadoc還提供了用於創建doclet和taglet的API，允許用戶分析Java應用程序的結構，這就是JDiff如何生成兩個API版本之間發生變化的報告。

Javadoc不影響Java中的性能，因為在編譯時會刪除所有注釋。編寫注釋和Javadoc是為了更好地理解代碼，從而更好地維護代碼。

歷史

Javadoc是早期的Java語言文檔生成器。在使用文檔生成器之前，習慣上由專業的技術編寫者編輯文檔，他們通常只編寫軟件的獨立文檔，但要使這些文檔與軟件本身保持同步要困難得多。

自第一個版本以來，Java一直使用Javadoc，並且通常在Java開發工具包的每個新版本上都會更新。

技術架構

Javadoc注釋結構

通過標準多行注釋標記/* and */從代碼中引發Javadoc注釋。起始標記（稱為開始 - 注釋分隔符）具有額外的星號，如/**中所示。

1. 第一段是對所記錄方法的描述。
2. 在描述之後是不同數量的描述性標籤，表示：
   1. 方法的參數（@param）
   2. 方法返回的內容（@return）
   3. 方法可能拋出的任何異常（@exception）
   4. 其他不太常見的標籤，如 @see （「另見」標籤）

Javadoc概覽

編寫文檔注釋的基本結構是將它們嵌入到/**.中。Javadoc寫在項目旁邊，沒有任何分隔換行符。請注意，任何import語句必須在類聲明之前。類聲明通常包括：

// import statements

/**
 * @author     姓名  <address @ example.com>
 * @version    1.6   （程序的当前版本号）
 * @since       1.2    （加入该类时程序的版本号）
 */
public class Test {
    // class body
}

對於方法，有如（1）所示的簡潔的一行描述來解釋項目的作用；接下來是（2）所示的更長的描述，該描述可以跨越多個段落並且是可有可無的；最後，第（3）部分列出接受的輸入參數和方法的返回值。所有的Javadoc都被視為HTML，因此多個段落部分由"<p>"段落符號分隔。

/**
 * 简短的单行描述。                                                  （1）
 * <p>
 * 更长一些的描述可以写在这里。                              （2）
 * </p>
 * 在HTML段落分隔的连续段落中还可以有更多注释。
 *
 * @param  variable 描述文本。                               （3）
 * @return  描述文本。
 */
public int methodName (...) {
    // method body with a return statement
}

與方法類似的注釋也可以用於變量的注釋，但省略了第（3）部分，這裡只包含了對變量的簡短描述：

/**
 * 对变量的描述。
 */
private int debug = 0;

請注意，不建議在單個文檔注釋中定義多個變量。這是因為Javadoc讀取每個變量並將它們分別放置到生成的HTML頁面，其中包含為所有字段複製的相同文檔注釋。

/**
 * 点对 (x,y) 的水平和垂直距离
 */
public int x, y;      // 避免这样的做法

相反，建議分別聲明和注釋每個變量：

/**
 * 点的水平距离。
 */
public int x;

/**
 * 点的垂直距离。
 */
public int y;

Javadoc標籤表

一部分可用的Javadoc標籤列在下表中：

標籤&參數	用途	適用於	引入版本
@author John Smith	描述作者。	類、接口、枚舉
{@docRoot}	表示從任何生成的頁面生成的文檔的根目錄的相對路徑。	類、接口、枚舉、成員、方法
@version 版本	提供軟件版本，每個類或接口最多一個。	類、接口、枚舉
@since 起始	描述此功能首次存在的時間。	類、接口、枚舉、成員、方法
@see 參考	提供指向其他文檔元素的鏈接。	類、接口、枚舉、成員、方法
@param 名稱 描述	描述方法的一個參數。	方法
@return 描述	描述返回值。	方法
@exception 類 描述 @throws 類 描述	描述可能從此方法拋出的異常。	方法
@deprecated 描述	描述一個過時的方法。	類、接口、枚舉、成員、方法
{@inheritDoc}	從被覆蓋的方法複製描述。	覆蓋方法	1.4.0
{@link 參考}	鏈接到其他符號。	類、接口、枚舉、成員、方法
{@linkplain 參考}	與{@link}相同，但鏈接的標籤以純文本顯示，而不是代碼字體。	類、接口、枚舉、成員、方法
{@value #STATIC_FIELD}	返回靜態成員的值。	靜態成員	1.4.0
{@code 文本}	在代碼字體中格式化文字文本，等同於<code> {@literal} </code>。	類、接口、枚舉、成員、方法	1.5.0
{@literal 文本}	表示文本，隨附的文本被解釋為不包含HTML標記或嵌套的javadoc標記。	類、接口、枚舉、成員、方法	1.5.0
{@serial 文本}	在Javadoc注釋中用於默認的可序列化字段。	成員
{@serialData 文本}	記錄writeObject()或writeExternal()方法寫入的數據。	成員、方法
{@serialField 文本}	記錄ObjectStreamField組件。	成員

示例

下面是注釋一個方法的Javadoc示例。

/**
 * 验证一步象棋的移动是否可行。
 *
 * <p>使用 {@link #doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)} 方法来移动棋子。
 *
 * @param theFromFile 被移动棋子的来源行
 * @param theFromRank 被移动棋子的来源列
 * @param theToFile  被移动棋子的目标行
 * @param theToRank  被移动棋子的目标列
 * @return            如果移动是可行的则返回true，否则返回false
 * @since             1.0
 */
boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
    // ...body
}

/**
 * 移动一个棋子。
 *
 * @see java.math.RoundingMode
 */
void doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)  {
    // ...body
}

參見

• 文檔生成器的比較
• .Net的XML文檔注釋