對於Java語言，最體貼的一項設計就是它並沒有打算讓人們為了寫程式而寫程式——人們也需要考慮程式的文件化問題。對於程式的文件化，最大的問題 莫過於對文件的維護。若文件與程式碼分離，那麼每次改變程式碼後都要改變文件，這無疑會變成相當麻煩的一件事情。解決的方法看起來似乎很簡單：將程式碼同文檔 “連結”起來。為達到這個目的，最簡單的方法是將所有內容都置於同一個檔案。然而，為使一切都整齊劃一，還必須使用一種特殊的註釋語法，以便標記出特殊的 文件；另外還需要一個工具，用於提取這些註釋，並按有價值的形式將其展現出來。這些都是Java必須做到的。
用於提取註釋的工具叫作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 變數文件標記
變數文件只能包括嵌入的HTML以及@see引用。

7 方法文件標記
除嵌入HTML和@see引用之外，方法還允許使用針對引數、返回值以及違例的文件標記。

1. @param
格式如下：
@param 引數名 說明
其中，“引數名”是指引數列表內的識別符號，而“說明”代表一些可延續到後續行內的說明文字。一旦遇到一個新文件標記，就認為前一個說明結束。可使用任意數量的說明，每個引數一個。

2. @return
格式如下：
@return 說明
其中，“說明”是指返回值的含義。它可延續到後面的行內。

3. @exception
有 關“違例”（Exception）的詳細情況，我們會在第9章講述。簡言之，它們是一些特殊的物件，若某個方法失敗，就可將它們“扔出”物件。呼叫一個方 法時，儘管只有一個違例物件出現，但一些特殊的方法也許能產生任意數量的、不同型別的違例。所有這些違例都需要說明。所以，違例標記的格式如下：
@exception 完整類名 說明
其中，“完整類名”明確指定了一個違例類的名字，它是在其他某個地方定義好的。而“說明”（同樣可以延續到下面的行）告訴我們為什麼這種特殊型別的違例會在方法呼叫中出現。

4. @deprecated
這是Java 1.1的新特性。該標記用於指出一些舊功能已由改進過的新功能取代。該標記的作用是建議使用者不必再使用一種特定的功能，因為未來改版時可能摒棄這一功能。若將一個方法標記為@deprecated，則使用該方法時會收到編譯器的警告。