Java 文檔註釋（學習 Java 編程語言 038）

JDK 包含一個頗有用的工具，叫作 javadoc, 它能夠由源文件生成一個 HTML 文檔。Java 的 API 文檔就是經過標準 Java 類庫的源代碼運行 javadoc 生成的。

若是在源代碼中添加以專用的定界符 /** 開始的註釋，能夠很容易地生成一個看上去具備專業水準的文檔。這是一種很好的方式，由於這種方式能夠將代碼與文檔註釋放在一個地方。若是將文檔註釋放在一個獨立的文件中，就有可能會隨着時間的推移出現代碼和文檔註釋不一致的問題。然而，因爲文檔註釋與源代碼在同一個文件中，在修改源代碼的同時，從新運行 javadoc 就能夠垂手可得地保持二者的一致性。

1. 註釋的插入

javadoc 實用工具從下面幾項中抽取信息：
 • 模塊
 • 包
 • 公共類和接口
 • 公共的和受保護的字段
 • 公共的和受保護的構造器和方法
能夠（並且應該）爲以上各個特性編寫註釋。註釋放置在所描述特性的前面。註釋一個 /** 開始，並以 */ 結束。

每一個 /** ... */ 文檔註釋包含標記以及以後緊跟着自由格式文本（free-form text）。標記以 @ 開始，如 @since 或 @param。

自由格式文本的第一句應該是一個概要性的句子。javadoc 工具自動地將這些句子抽取出生成概要頁。

在自由格式文本中，可使用 HTML 修飾符，例如：

• 用於強調 <em>...</em>。
• 用於着重強調<strong>...</strong>。
• 用戶項目符號列表的 <ul>/<li>。
• 用於包含圖像的 <img ...>。
• 用於等寬代碼 {@code ...}， 而不是 <code>...</code> —— 這樣一來，就不用操心對代碼中的 < 字符轉移了。

註釋：若是文檔中有到其餘文件的連接，如圖像文件（例如，圖標或用戶界面組件的圖像），就應該將這些文件放到包含源文件的目錄下的一個子目錄 doc-files 中。javadoc 工具將從源目錄將 doc-files 目錄及其內容拷貝到文檔目錄中。在連接中須要使用 doc-files 目錄，例如：<img src="doc-files/uml_png" alt="UML diagram" >。

2. 類註釋

類註釋必須放在 import 語句以後，類定義以前。

下面是一個類註釋的例子：

/**
 * A {@code Card} object represents a playing card, such
 * as "Queen of Hearts". A card has a suit (Diamond, Heart,
 * Spade or Club) and a value (1 = Ace, 2 . . . 10, 11 = Jack,
 * 12 = Queen, 13 = King)
 */
public class Card{
    ...
}

沒有必要在每一行的開始用星號 *， 例如， 如下注釋一樣是合法的：

/**
 A {@code Card} object represents a playing card, such
 as "Queen of Hearts". A card has a suit (Diamond, Heart,
 Spade or Club) and a value (1 = Ace, 2 . . . 10, 11 = Jack,
 12 = Queen, 13 = King)
 */
public class Card{
    ...
}

3. 方法註釋

每個方法註釋必須放在所描述的方法以前。除了通用標記以外，還可使用下面的標記：

• @param variable description（變量描述）

  這個標記將對當前方法的 「parameters」 （參數）部分添加一個條目。這個描述能夠佔據多行，並可使用 HTML 標記。一個方法的全部 @param 標記必須放在一塊兒。

• @return description（描述）

  這個標記將對當前方法添加 「returns」 （返回）部分。這個描述能夠跨越多行，並可使用 HTML 標記。

• @throws class description（類描述）

  這個標記將添加一個註釋，用於表示這個方法有可能拋出異常。

下面是一個合法註釋示例：

/**
     * Raises the salary of an employee.
     * @param byPercent the percentage by which to raise the salary (e.g. 10 means 10%)
     * @return the amount of the raise
     */
    public double raiseSalary(double byPercent) {
        double raise = salary * byPercent / 100;
        salary += raise;
        return raise;
    }

4. 字段註釋

只須要對公有字段（一般指的是靜態常量）創建文檔。

/**
     * The "Hearts" card suit
     */
    public static final int HEARST = 1;

5. 通用註釋

5.1 用在類文檔註釋的標記

• @author 姓名

  這個標記將產生一個 「author」 (做者）條目。可使用多個 @author 標記，每一個 @author 標記對應一個做者。並非非得使用這個標記，你的版本控制系統可以更好地跟蹤做者。

• @version 文本

  這個標記將產生一個 「version」（版本）條目。這裏的文本能夠是對當前版本的任何描述。

5.2 能夠用在全部文件註釋的標記

• @since 文本

  這個標記將產生一個 「since」 （始於）條目。這裏的 text 能夠是對引入這個特性的版本的任何描述。例如， @since 1.7.1

• @deprecated 文本

  這個標記將對類、方法或變量添加一個再也不使用的註釋。文本中給出了取代的建議。例如，
  @deprecated Use <code>setVIsible(true)</code> instead
  經過 @see 和 @link 標記， 可使用超級連接， 連接到 javadoc 文檔的相關部分或外部文檔。

• @see 引用

  這個標記將在 「see also」 部分增長一個超級連接。它能夠用於類中，也能夠用於方法中。這裏的 reference（引用）能夠有如下選擇：
   1. package.class#feature label
   2. <a href="...">label/a>
   2. "text"
  第一種狀況是最有用。只要提供類、方法或變量的名字，javadoc 就在文檔中插入一個超連接。例如，
   @see com.xiang117.corejava.Employee#raiseSalary(double)
  會創建一個連接到 com.horstmann.corejava.Employee 類的 raiseSalary(double) 方法的超連接。能夠省略包名，甚至把包名和類名都省去，這樣一來，這會定位於當前包或當前類中。
  須要注意，必定要使用井號（#），而不要使用點號（.）分隔類名與方法名，或類名與變量名。Java 編譯器自身能夠熟練地肯定點號在分隔包、子包、類、內部類與方法和變量時的不一樣含義。可是 javadoc 工具就沒有這麼聰明瞭，所以必須對它提供幫助。

  若是 @see 標記後面有一個 < 字符，就須要指定一個超連接。能夠超連接到任何 URL。例如：
   @see <a href="www.xiang117.com/corejava.html">The Core Java home page</a>
 @see <a href="http://www.baidu.com">百度</a>
  在上述各類狀況下，均可以指定一個可選的標籤（label）做爲連接錨（link anchor）。若是省略了標籤，用戶看到的錨就是目標代碼名或 URL。

  若是 @see 標記後面有一個雙引號（"）字符，文本就會顯示在 「see also」 部分。例如，
   @see "Core Java 2 volume 2"

  能夠爲一個特性添加多個 @see 標記，但必須將它們放在一塊兒。

• @link

  若是願意，還能夠在文檔註釋中的任何位置放置指向其餘類或方法的超連接，能夠在註釋中的任何位置插入一個形式以下的特殊標記：
   {@link package.class#feature label}
  這裏的特性描述規則與 @see 標記規相同。

• @index

  在 Java 9 中，還可使用 {@index entry} 標記爲搜索框增長一個條目。

6. 包註釋

能夠直接將類、方法和變量的註釋放置在 Java 源文件中，只要用 /** . . . */ 文檔註釋界定就能夠了。可是，要想產生包註釋，就須要在每個包目錄中添加一個單獨的文件。能夠有以下兩個選擇：

1. 提供一個名爲 package-info.java 的 Java 文件。這個文件必須包含一個初始的以 /** 和 */ 界定的 Javadoc 註釋，後面是一個 package 語句。它不該該包含更多的代碼或註釋。
2. 提供一個名爲 package.html 的 HTML 文件。會抽取標記 <body>...</body>之間的全部文本。

7. 註釋抽取

假設但願 HTML 文件將放在名爲 docDirectory 的目錄下。執行如下步驟：

1. 切換到包含想要生成文檔的源文件的目錄。若是有嵌套的包要生成文檔，例如 com.
   xiang117.corejava, 就必須切換到包含子目錄 com 的目錄（若是提供了 overview.html 文件的
   話，這就是這個文件所在的目錄)。
2. 若是是一個包，應該運行命令:
    javadoc -d docDirectory nameOfPackage
   若是要爲多個包生成文檔，運行:
    javadoc -d docDirectory nameOfPackage1 nameOfPackage2
   若是文件在無名的包中，就應該運行：
    javadoc -d docDirectory *.java

若是省略了 -d docDirectory 選項，那 HTML 文件就會被提取到當前目錄下。這樣有可能會帶來混亂，所以不提倡這種作法。

可使用不少命令行選項對 javadoc 程序進行優化。例如，可使用 -author 和 -version 選項在文檔中包含 @author 和 @version 標記（默認狀況下，這些標記會被省略 )。另外一個頗有用的選項是 -link，用來爲標準類添加超連接。例如，若是使用命令
 javadoc -link http://docs.oracle.com/javase/9/docs/api *.java
那麼，全部的標準類庫類都會自動地連接到 Oracle 網站的文檔。

若是使用 -linksource 選項，則每一個源文件將會被轉換爲 HTML (不對代碼着色，但包含行號)，而且每一個類和方法名將變爲指向源代碼的超連接。

還能夠爲全部的源文件提供一個概要註釋。把它放在一個相似 overview.html 的文件中，運行 javadoc 工具，並提供命令行選項 -overview filename。將抽取標記 <body>...</body> 之間的全部文本。當用戶長導航欄中選擇 「Overview」（概覽）時，就會顯示出這些內容。

有關其餘的選項，請查閱 javadoc 工具的聯機文檔 https://docs.oracle.com/javase/9/javadoc/javadoc.htm。