對于java語言，最體貼的一項設計就是它并沒有打算讓人們為了寫程序而寫程序。對于程序的文檔化，最大的問題莫過于對文檔的維護。若文檔與代碼分離，那么每次改變代碼后都要改變文檔，這無疑會變成相當麻煩的一件事情。解決的方法看起來似乎很簡單：將代碼同文檔“鏈接”起來。為達到這個目的，最簡單的方法是將所有內容都置于同一個文件。然而，為使一切都整潔劃一，還必須使用一種非凡的注釋語法，以便標記出非凡的文檔；另外還需要一個工具，用于提取這些注釋，并按有價值的形式將其展現出來。這些都是Java必須做到的。

1 javadoc

用于提取注釋的工具叫作javadoc。它采用了部分來自Java編譯器的技術，查找我們置入程序的非凡注釋標記。它不僅提取由這些標記指示的信息，也將毗鄰注釋的類名或方法名提取出來。這樣一來，我們就可用最輕的工作量，生成十分專業的程序文檔。

javadoc輸出的是一個Html文件，可用自己的Web瀏覽器查看。該工具答應我們創建和治理單個源文件，并生動生成有用的文檔。由于有了jvadoc，所以我們能夠用標準的方法創建文檔。而且由于它非常方便，所以我們能輕松獲得所有Java庫的文檔。

2 具體語法

所有javadoc命令都只能出現于“/**”注釋中。但和平常一樣，注釋結束于一個“*/”。主要通過兩種方式來使用javadoc：嵌入的HTML，或使用“文檔標記”。其中，“文檔標記”（Doc tags）是一些以“@”開頭的命令，置于注釋行的起始處（但前導的“*”會被忽略）。

有三種類型的注釋文檔，它們對應于位于注釋后面的元素：類、變量或者方法。也就是說，一個類注釋正好位于一個類定義之前；變量注釋正好位于變量定義之前；而一個方法定義正好位于一個方法定義的前面。如下面這個簡單的例子所示：

/** 一個類注釋 */

public class docTest {

/** 一個變量注釋 */

public int i;

/** 一個方法注釋 */

public void f() {}

}

注重javadoc只能為public（公共）和PRotected（受保護）成員處理注釋文檔。“private”（私有）和“友好”（詳見5章）成員的注釋會被忽略，我們看不到任何輸出（也可以用-private標記包括private成員）。這樣做是有道理的，因為只有public和protected成員才可在文件之外使用，這是客戶程序員的希望。然而，所有類注釋都會包含到輸出結果里。

上述代碼的輸出是一個HTML文件，它與其他Java文檔具有相同的標準格式。因此，用戶會非常熟悉這種格式，可在您設計的類中方便地“漫游”。設計程序時，請務必考慮輸入上述代碼，用javadoc處理一下，觀看最終HTML文件的效果如何。

3 嵌入HTML

javadoc將HTML命令傳遞給最終生成的HTML文檔。這便使我們能夠充分利用HTML的巨大威力。當然，我們的最終動機是格式化代碼，不是為了嘩眾取寵。下面列出一個例子：

/**

*

* System.out.println(new Date());

*

*/

亦可象在其他Web文檔里那樣運用HTML，對普通文本進行格式化，使其更具條理、更加美觀：

/**

* 您甚至可以插入一個列表：

*

*

項目一

*

項目二

*

項目三

*

*/

注重在文檔注釋中，位于一行最開頭的星號會被javadoc丟棄。同時丟棄的還有前導空格。javadoc會對所有內容進行格式化，使其與標準的文檔外觀相符。不要將

或

這樣的標題當作嵌入HTML使用，因為javadoc會插入自己的標題，我們給出的標題會與之沖撞。

所有類型的注釋文檔??類、變量和方法??都支持嵌入HTML。

4 @see：引用其他類

所有三種類型的注釋文檔都可包含@see標記，它答應我們引用其他類里的文檔。對于這個標記，javadoc會生成相應的HTML，將其直接鏈接到其他文檔。格式如下：

@see 類名

@see 完整類名

@see 完整類名

每一格式都會在生成的文檔里自動加入一個超鏈接的“See Also”（參見）條目。注重javadoc不會檢查我們指定的超鏈接，不會驗證它們是否有效。

5 類文檔標記

隨同嵌入HTML和@see引用，類文檔還可以包括用于版本信息以及作者姓名的標記。類文檔亦可用于“接口”目的。

1. @version

格式如下：

@version 版本信息

其中，“版本信息”代表任何適合作為版本說明的資料。若在javadoc命令行使用了“-version”標記，就會從生成的HTML文檔里提取出版本信息。

2. @author

格式如下：

@author 作者信息

其中，“作者信息”包括您的姓名、電子函件地址或者其他任何適宜的資料。若在javadoc命令行使用了“-author”標記，就會專門從生成的HTML文檔里提取出作者信息。

可為一系列作者使用多個這樣的標記，但它們必須連續放置。全部作者信息會一起存入最終HTML代碼的單獨一個段落里。

6 變量文檔標記