Javadoc

<image>

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注釋。起始標記（稱為開始 - 注釋分隔符）具有額外的星號，如`/**`中所示。

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

### Javadoc概覽

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

```java
// import statements

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

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

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

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

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

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

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

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

```java
/**
 * 点的水平距离。
 */
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示例。

```java
/**
 * 验证一步象棋的移动是否可行。
 *
 * <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
}
```