JDK 包含一個(gè)很有用的工具豆赏，叫做 javadoc, 它可以由源文件生成一個(gè) HTML 文檔竞膳。Java 的 API 文檔就是通過標(biāo)準(zhǔn) Java 類庫的源代碼運(yùn)行 javadoc 生成的。
如果在源代碼中添加以專用的定界符 /** 開始的注釋汇跨，可以很容易地生成一個(gè)看上去具有專業(yè)水準(zhǔn)的文檔呛占。這是一種很好的方式，因?yàn)檫@種方式可以將代碼與文檔注釋放在一個(gè)地方暴区。如果將文檔注釋放在一個(gè)獨(dú)立的文件中闯团，就有可能會(huì)隨著時(shí)間的推移出現(xiàn)代碼和文檔注釋不一致的問題。然而仙粱，由于文檔注釋與源代碼在同一個(gè)文件中房交，在修改源代碼的同時(shí)，重新運(yùn)行 javadoc 就可以輕而易舉地保持兩者的一致性伐割。
1. 注釋的插入
javadoc 實(shí)用工具從下面幾項(xiàng)中抽取信息：
?? 模塊
?? 包
?? 公共類和接口
?? 公共的和受保護(hù)的字段
?? 公共的和受保護(hù)的構(gòu)造器和方法
可以（而且應(yīng)該）為以上各個(gè)特性編寫注釋候味。注釋放置在所描述特性的前面。注釋一個(gè) /** 開始隔心，并以 */ 結(jié)束白群。
每個(gè) /** ... */ 文檔注釋包含標(biāo)記以及之后緊跟著自由格式文本（free-form text）。標(biāo)記以 @ 開始硬霍，如 @since 或 @param帜慢。
自由格式文本的第一句應(yīng)該是一個(gè)概要性的句子。javadoc 工具自動(dòng)地將這些句子抽取出生成概要頁。
在自由格式文本中粱玲，可以使用 HTML 修飾符躬柬，例如：
- 用于強(qiáng)調(diào)
<em>...</em>。 - 用于著重強(qiáng)調(diào)
<strong>...</strong>抽减。 - 用戶項(xiàng)目符號(hào)列表的
<ul>/<li>允青。 - 用于包含圖像的
<img ...>。 - 用于等寬代碼 {@code ...}胯甩， 而不是
<code>...</code>—— 這樣一來昧廷，就不用操心對(duì)代碼中的<字符轉(zhuǎn)移了。
注釋：如果文檔中有到其他文件的鏈接偎箫，如圖像文件（例如木柬，圖標(biāo)或用戶界面組件的圖像），就應(yīng)該將這些文件放到包含源文件的目錄下的一個(gè)子目錄 doc-files 中淹办。javadoc 工具將從源目錄將 doc-files 目錄及其內(nèi)容拷貝到文檔目錄中眉枕。在鏈接中需要使用 doc-files 目錄，例如：<img src="doc-files/uml_png" alt="UML diagram" >怜森。
2. 類注釋
類注釋必須放在 import 語句之后速挑，類定義之前。
下面是一個(gè)類注釋的例子：
/**
* 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{
...
}
沒有必要在每一行的開始用星號(hào) *副硅， 例如姥宝， 以下注釋同樣是合法的：
/**
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. 方法注釋
每一個(gè)方法注釋必須放在所描述的方法之前。除了通用標(biāo)記之外恐疲，還可以使用下面的標(biāo)記：
- @param variable description（變量描述）
這個(gè)標(biāo)記將對(duì)當(dāng)前方法的 “parameters” （參數(shù)）部分添加一個(gè)條目腊满。這個(gè)描述可以占據(jù)多行，并可以使用 HTML 標(biāo)記培己。一個(gè)方法的所有 @param 標(biāo)記必須放在一起碳蛋。
- @return description（描述）
這個(gè)標(biāo)記將對(duì)當(dāng)前方法添加 “returns” （返回）部分。這個(gè)描述可以跨越多行省咨，并可以使用 HTML 標(biāo)記肃弟。
- @throws class description（類描述）
這個(gè)標(biāo)記將添加一個(gè)注釋，用于表示這個(gè)方法有可能拋出異常零蓉。
下面是一個(gè)合法注釋示例：
/**
* 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. 字段注釋
只需要對(duì)公有字段（通常指的是靜態(tài)常量）建立文檔笤受。
/**
* The "Hearts" card suit
*/
public static final int HEARST = 1;
5. 通用注釋
5.1 用在類文檔注釋的標(biāo)記
- @author 姓名
這個(gè)標(biāo)記將產(chǎn)生一個(gè) “author” (作者）條目〉蟹洌可以使用多個(gè) @author 標(biāo)記感论，每個(gè) @author 標(biāo)記對(duì)應(yīng)一個(gè)作者。并不是非得使用這個(gè)標(biāo)記紊册，你的版本控制系統(tǒng)能夠更好地跟蹤作者。
- @version 文本
這個(gè)標(biāo)記將產(chǎn)生一個(gè) “version”（版本）條目。這里的文本可以是對(duì)當(dāng)前版本的任何描述囊陡。
5.2 可以用在所有文件注釋的標(biāo)記
- @since 文本
這個(gè)標(biāo)記將產(chǎn)生一個(gè) “since” （始于）條目芳绩。這里的 text 可以是對(duì)引入這個(gè)特性的版本的任何描述。例如撞反，
@since 1.7.1 - @deprecated 文本
這個(gè)標(biāo)記將對(duì)類妥色、方法或變量添加一個(gè)不再使用的注釋。文本中給出了取代的建議遏片。例如嘹害，
@deprecated Use <code>setVIsible(true)</code> instead
通過 @see 和 @link 標(biāo)記， 可以使用超級(jí)鏈接吮便， 鏈接到 javadoc 文檔的相關(guān)部分或外部文檔笔呀。 - @see 引用
這個(gè)標(biāo)記將在 “see also” 部分增加一個(gè)超級(jí)鏈接。它可以用于類中髓需，也可以用于方法中许师。這里的 reference（引用）可以有以下選擇：
?1.package.class#feature label
?2.<a href="...">label/a>
?2."text"
第一種情況是最有用。只要提供類僚匆、方法或變量的名字微渠，javadoc 就在文檔中插入一個(gè)超鏈接。例如咧擂，
?@see com.xiang117.corejava.Employee#raiseSalary(double)
會(huì)建立一個(gè)鏈接到com.horstmann.corejava.Employee類的raiseSalary(double)方法的超鏈接逞盆。可以省略包名松申，甚至把包名和類名都省去云芦，這樣一來，這會(huì)定位于當(dāng)前包或當(dāng)前類中攻臀。
需要注意焕数，一定要使用井號(hào)（#），而不要使用點(diǎn)號(hào)（.）分隔類名與方法名刨啸，或類名與變量名堡赔。Java 編譯器自身可以熟練地確定點(diǎn)號(hào)在分隔包、子包设联、類善已、內(nèi)部類與方法和變量時(shí)的不同含義。但是 javadoc 工具就沒有這么聰明了离例，因此必須對(duì)它提供幫助换团。如果 @see 標(biāo)記后面有一個(gè)
<字符，就需要指定一個(gè)超鏈接宫蛆∷野可以超鏈接到任何 URL的猛。例如：
?@see <a href="www.xiang117.com/corejava.html">The Core Java home page</a>
?@see <a >百度</a>
在上述各種情況下，都可以指定一個(gè)可選的標(biāo)簽（label）作為鏈接錨（link anchor）想虎。如果省略了標(biāo)簽卦尊，用戶看到的錨就是目標(biāo)代碼名或 URL。如果 @see 標(biāo)記后面有一個(gè)雙引號(hào)（"）字符舌厨，文本就會(huì)顯示在 “see also” 部分岂却。例如，
?@see "Core Java 2 volume 2"可以為一個(gè)特性添加多個(gè) @see 標(biāo)記裙椭，但必須將它們放在一起躏哩。
- @link
如果愿意，還可以在文檔注釋中的任何位置放置指向其他類或方法的超鏈接揉燃，可以在注釋中的任何位置插入一個(gè)形式如下的特殊標(biāo)記：
?{@link package.class#feature label}
這里的特性描述規(guī)則與 @see 標(biāo)記規(guī)相同扫尺。 - @index
在 Java 9 中，還可以使用
{@index entry}標(biāo)記為搜索框增加一個(gè)條目你雌。
6. 包注釋
可以直接將類器联、方法和變量的注釋放置在 Java 源文件中，只要用 /** . . . */ 文檔注釋界定就可以了婿崭。但是拨拓，要想產(chǎn)生包注釋，就需要在每一個(gè)包目錄中添加一個(gè)單獨(dú)的文件氓栈≡祝可以有如下兩個(gè)選擇：
- 提供一個(gè)名為 package-info.java 的 Java 文件。這個(gè)文件必須包含一個(gè)初始的以
/**和*/界定的 Javadoc 注釋授瘦，后面是一個(gè) package 語句醋界。它不應(yīng)該包含更多的代碼或注釋。 - 提供一個(gè)名為 package.html 的 HTML 文件提完。會(huì)抽取標(biāo)記
<body>...</body>之間的所有文本形纺。
7. 注釋抽取
假設(shè)希望 HTML 文件將放在名為 docDirectory 的目錄下。執(zhí)行以下步驟：
- 切換到包含想要生成文檔的源文件的目錄徒欣。如果有嵌套的包要生成文檔逐样，例如 com.
xiang117.corejava, 就必須切換到包含子目錄 com 的目錄（如果提供了 overview.html 文件的
話，這就是這個(gè)文件所在的目錄)打肝。 - 如果是一個(gè)包脂新，應(yīng)該運(yùn)行命令:
?javadoc -d docDirectory nameOfPackage
如果要為多個(gè)包生成文檔，運(yùn)行:
?javadoc -d docDirectory nameOfPackage1 nameOfPackage2
如果文件在無名的包中粗梭，就應(yīng)該運(yùn)行：
?javadoc -d docDirectory *.java
如果省略了 -d docDirectory 選項(xiàng)争便，那 HTML 文件就會(huì)被提取到當(dāng)前目錄下。這樣有可能會(huì)帶來混亂断医，因此不提倡這種做法滞乙。
可以使用很多命令行選項(xiàng)對(duì) javadoc 程序進(jìn)行優(yōu)化奏纪。例如，可以使用 -author 和 -version 選項(xiàng)在文檔中包含 @author 和 @version 標(biāo)記（默認(rèn)情況下酷宵，這些標(biāo)記會(huì)被省略 )亥贸。另一個(gè)很有用的選項(xiàng)是 -link，用來為標(biāo)準(zhǔn)類添加超鏈接浇垦。例如，如果使用命令
?javadoc -link http://docs.oracle.com/javase/9/docs/api *.java
那么荣挨，所有的標(biāo)準(zhǔn)類庫類都會(huì)自動(dòng)地鏈接到 Oracle 網(wǎng)站的文檔男韧。
如果使用 -linksource 選項(xiàng)，則每個(gè)源文件將會(huì)被轉(zhuǎn)換為 HTML (不對(duì)代碼著色默垄，但包含行號(hào))此虑，并且每個(gè)類和方法名將變?yōu)橹赶蛟创a的超鏈接。
還可以為所有的源文件提供一個(gè)概要注釋口锭。把它放在一個(gè)類似 overview.html 的文件中朦前，運(yùn)行 javadoc 工具，并提供命令行選項(xiàng) -overview filename鹃操。將抽取標(biāo)記 <body>...</body> 之間的所有文本韭寸。當(dāng)用戶長(zhǎng)導(dǎo)航欄中選擇 “Overview”（概覽）時(shí)，就會(huì)顯示出這些內(nèi)容荆隘。
有關(guān)其他的選項(xiàng)恩伺，請(qǐng)查閱 javadoc 工具的聯(lián)機(jī)文檔 https://docs.oracle.com/javase/9/javadoc/javadoc.htm。
