對(duì)于Java語(yǔ)言，最體貼的一項(xiàng)設(shè)計(jì)就是它并沒(méi)有打算讓人們?yōu)榱藢?xiě)程序而寫(xiě)程序——人們也需要考慮程序的文檔化問(wèn)題。對(duì)于程序的文檔化，的問(wèn)題莫過(guò)于對(duì)文檔的維護(hù)。若文檔與代碼分離，那么每次改變代碼后都要改變文檔，這無(wú)疑會(huì)變成相當(dāng)麻煩的一件事情。解決的方法看起來(lái)似乎很簡(jiǎn)單：將代碼同文檔“鏈接”起來(lái)。為達(dá)到這個(gè)目的，最簡(jiǎn)單的方法是將所有內(nèi)容都置于同一個(gè)文件。然而，為使一切都整齊劃一，還必須使用一種特殊的注釋語(yǔ)法，以便標(biāo)記出特殊的文檔；另外還需要一個(gè)工具，用于提取這些注釋?zhuān)从袃r(jià)值的形式將其展現(xiàn)出來(lái)。這些都是Java必須做到的。
用于提取注釋的工具叫作javadoc。它采用了部分來(lái)自Java編譯器的技術(shù)，查找我們置入程序的特殊注釋標(biāo)記。它不僅提取由這些標(biāo)記指示的信息，也將毗鄰注釋的類(lèi)名或方法名提取出來(lái)。這樣一來(lái)，我們就可用最輕的工作量，生成十分專(zhuān)業(yè)的程序文檔。
javadoc輸出的是一個(gè)HTML文件，可用自己的Web瀏覽器查看。該工具允許我們創(chuàng)建和管理單個(gè)源文件，并生動(dòng)生成有用的文檔。由于有了jvadoc，所以我們能夠用標(biāo)準(zhǔn)的方法創(chuàng)建文檔。而且由于它非常方便，所以我們能輕松獲得所有Java庫(kù)的文檔。
具體語(yǔ)法
所有javadoc命令都只能出現(xiàn)于“/**”注釋中。但和平常一樣，注釋結(jié)束于一個(gè)“*/”。主要通過(guò)兩種方式來(lái)使用javadoc：嵌入的HTML，或使用“文檔標(biāo)記”。其中，“文檔標(biāo)記”（Doc tags）是一些以“@”開(kāi)頭的命令，置于注釋行的起始處（但前導(dǎo)的“*”會(huì)被忽略）。
有三種類(lèi)型的注釋文檔，它們對(duì)應(yīng)于位于注釋后面的元素：類(lèi)、變量或者方法。也就是說(shuō)，一個(gè)類(lèi)注釋正好位于一個(gè)類(lèi)定義之前；變量注釋正好位于變量定義之前；而一個(gè)方法定義正好位于一個(gè)方法定義的前面。如下面這個(gè)簡(jiǎn)單的例子所示：
/** 一個(gè)類(lèi)注釋 */
public class docTest {
/** 一個(gè)變量注釋 */
public int i;
/** 一個(gè)方法注釋 */
public void f() {}
}
注意javadoc只能為public（公共）和protected（受保護(hù)）成員處理注釋文檔。“private”（私有）和“友好”（詳見(jiàn)5章）成員的注釋會(huì)被忽略，我們看不到任何輸出（也可以用-private標(biāo)記包括private成員）。這樣做是有道理的，因?yàn)橹挥衟ublic和protected成員才可在文件之外使用，這是客戶(hù)程序員的希望。然而，所有類(lèi)注釋都會(huì)包含到輸出結(jié)果里。
上述代碼的輸出是一個(gè)HTML文件，它與其他Java文檔具有相同的標(biāo)準(zhǔn)格式。因此，用戶(hù)會(huì)非常熟悉這種格式，可在您設(shè)計(jì)的類(lèi)中方便地“漫游”。設(shè)計(jì)程序時(shí)，請(qǐng)務(wù)必考慮輸入上述代碼，用javadoc處理一下，觀看最終HTML文件的效果如何。
嵌入HTML
javadoc將HTML命令傳遞給最終生成的HTML文檔。這便使我們能夠充分利用HTML的巨大威力。當(dāng)然，我們的最終動(dòng)機(jī)是格式化代碼，不是為了嘩眾取寵。下面列出一個(gè)例子：
/**
*
*/
亦可象在其他Web文檔里那樣運(yùn)用HTML，對(duì)普通文本進(jìn)行格式化，使其更具條理、更加美觀：
/**
* 您甚至可以插入一個(gè)列表：
*
*/
注意在文檔注釋中，位于一行最開(kāi)頭的星號(hào)會(huì)被javadoc丟棄。同時(shí)丟棄的還有前導(dǎo)空格。javadoc會(huì)對(duì)所有內(nèi)容進(jìn)行格式化，使其與標(biāo)準(zhǔn)的文檔外觀相符。不要將或這樣的標(biāo)題當(dāng)作嵌入HTML使用，因?yàn)閖avadoc會(huì)插入自己的標(biāo)題，我們給出的標(biāo)題會(huì)與之沖撞。
所有類(lèi)型的注釋文檔——類(lèi)、變量和方法——都支持嵌入HTML。
@see：引用其他類(lèi)
所有三種類(lèi)型的注釋文檔都可包含@see標(biāo)記，它允許我們引用其他類(lèi)里的文檔。對(duì)于這個(gè)標(biāo)記，javadoc會(huì)生成相應(yīng)的HTML，將其直接鏈接到其他文檔。格式如下：
@see 類(lèi)名
@see 完整類(lèi)名
@see 完整類(lèi)名#方法名
每一格式都會(huì)在生成的文檔里自動(dòng)加入一個(gè)超鏈接的“See Also”（參見(jiàn)）條目。注意javadoc不會(huì)檢查我們指定的超鏈接，不會(huì)驗(yàn)證它們是否有效。
用于提取注釋的工具叫作javadoc。它采用了部分來(lái)自Java編譯器的技術(shù)，查找我們置入程序的特殊注釋標(biāo)記。它不僅提取由這些標(biāo)記指示的信息，也將毗鄰注釋的類(lèi)名或方法名提取出來(lái)。這樣一來(lái)，我們就可用最輕的工作量，生成十分專(zhuān)業(yè)的程序文檔。
javadoc輸出的是一個(gè)HTML文件，可用自己的Web瀏覽器查看。該工具允許我們創(chuàng)建和管理單個(gè)源文件，并生動(dòng)生成有用的文檔。由于有了jvadoc，所以我們能夠用標(biāo)準(zhǔn)的方法創(chuàng)建文檔。而且由于它非常方便，所以我們能輕松獲得所有Java庫(kù)的文檔。
具體語(yǔ)法
所有javadoc命令都只能出現(xiàn)于“/**”注釋中。但和平常一樣，注釋結(jié)束于一個(gè)“*/”。主要通過(guò)兩種方式來(lái)使用javadoc：嵌入的HTML，或使用“文檔標(biāo)記”。其中，“文檔標(biāo)記”（Doc tags）是一些以“@”開(kāi)頭的命令，置于注釋行的起始處（但前導(dǎo)的“*”會(huì)被忽略）。
有三種類(lèi)型的注釋文檔，它們對(duì)應(yīng)于位于注釋后面的元素：類(lèi)、變量或者方法。也就是說(shuō)，一個(gè)類(lèi)注釋正好位于一個(gè)類(lèi)定義之前；變量注釋正好位于變量定義之前；而一個(gè)方法定義正好位于一個(gè)方法定義的前面。如下面這個(gè)簡(jiǎn)單的例子所示：
/** 一個(gè)類(lèi)注釋 */
public class docTest {
/** 一個(gè)變量注釋 */
public int i;
/** 一個(gè)方法注釋 */
public void f() {}
}
注意javadoc只能為public（公共）和protected（受保護(hù)）成員處理注釋文檔。“private”（私有）和“友好”（詳見(jiàn)5章）成員的注釋會(huì)被忽略，我們看不到任何輸出（也可以用-private標(biāo)記包括private成員）。這樣做是有道理的，因?yàn)橹挥衟ublic和protected成員才可在文件之外使用，這是客戶(hù)程序員的希望。然而，所有類(lèi)注釋都會(huì)包含到輸出結(jié)果里。
上述代碼的輸出是一個(gè)HTML文件，它與其他Java文檔具有相同的標(biāo)準(zhǔn)格式。因此，用戶(hù)會(huì)非常熟悉這種格式，可在您設(shè)計(jì)的類(lèi)中方便地“漫游”。設(shè)計(jì)程序時(shí)，請(qǐng)務(wù)必考慮輸入上述代碼，用javadoc處理一下，觀看最終HTML文件的效果如何。
嵌入HTML
javadoc將HTML命令傳遞給最終生成的HTML文檔。這便使我們能夠充分利用HTML的巨大威力。當(dāng)然，我們的最終動(dòng)機(jī)是格式化代碼，不是為了嘩眾取寵。下面列出一個(gè)例子：
/**
*
* System.out.println(new Date());
*
*/
亦可象在其他Web文檔里那樣運(yùn)用HTML，對(duì)普通文本進(jìn)行格式化，使其更具條理、更加美觀：
/**
* 您甚至可以插入一個(gè)列表：
*
- 項(xiàng)目一
* - 項(xiàng)目二
* - 項(xiàng)目三
*
*
*/
注意在文檔注釋中，位于一行最開(kāi)頭的星號(hào)會(huì)被javadoc丟棄。同時(shí)丟棄的還有前導(dǎo)空格。javadoc會(huì)對(duì)所有內(nèi)容進(jìn)行格式化，使其與標(biāo)準(zhǔn)的文檔外觀相符。不要將或這樣的標(biāo)題當(dāng)作嵌入HTML使用，因?yàn)閖avadoc會(huì)插入自己的標(biāo)題，我們給出的標(biāo)題會(huì)與之沖撞。
所有類(lèi)型的注釋文檔——類(lèi)、變量和方法——都支持嵌入HTML。
@see：引用其他類(lèi)
所有三種類(lèi)型的注釋文檔都可包含@see標(biāo)記，它允許我們引用其他類(lèi)里的文檔。對(duì)于這個(gè)標(biāo)記，javadoc會(huì)生成相應(yīng)的HTML，將其直接鏈接到其他文檔。格式如下：
@see 類(lèi)名
@see 完整類(lèi)名
@see 完整類(lèi)名#方法名
每一格式都會(huì)在生成的文檔里自動(dòng)加入一個(gè)超鏈接的“See Also”（參見(jiàn)）條目。注意javadoc不會(huì)檢查我們指定的超鏈接，不會(huì)驗(yàn)證它們是否有效。