對於Java註釋我們主要了解兩種：
// 註釋一行
/* ...... */ 註釋若干行
但還有第三種，文檔註釋：
/** ...... */ 註釋若干行，並寫入 javadoc 文檔
通常這種註釋的多行寫法如下：
/**
* .........
* .........
*/
很多人多忽視了這第三種註釋，那麼這第三種註釋有什麼用？javadoc 又是什麼東西？下面我們就談談。
一. Java 文檔和 Javadoc
Java 程序員都應該知道使用 JDK 開發，最好的幫助信息就來自 SUN 發佈的 Java 文檔。它分包、分類詳細的提供了各方法、屬性的幫助信息，具有詳細的類樹信息、索引信息等，並提供了許多相關類之間的關係，如繼承、實現接口、引用等。
Java 文檔全是由一些 html 文件組織起來的，在 SUM 的站點上可以下載它們的壓縮包。但是你肯定想不到，這些文檔我們可以自己生成。——就此打住，再吊一次胃口。
安裝了 JDK 之後，安裝目錄下有一個 src.jar 文件或者 src.zip 文件，它們都是以 ZIP 格式壓縮的，可以使用 WinZip 解壓。解壓之後，我們就可以看到分目錄放的全是 .java 文件。是了，這些就是 Java 運行類的源碼了，非常完整，連註釋都寫得一清二楚……不過，怎麼看這些註釋都有點似曾相識的感覺？
這就不奇怪了，我們的迷底也快要揭開了。如果你仔細對比一下 .java 源文件中的文檔註釋 (/** ... */) 和 Java 文檔的內容，你會發現它們就是一樣的。Java 文檔只是還在格式和排版上下了些功夫。再仔細一點，你會發現 .java 源文件中的註釋還帶有 HTML 標識，如 ＜B＞、＜BR＞、＜Code＞ 等，在 Java 文檔中，該出現這些標識的地方，已經按標識的的定義進行了排版。
終於真像大白了，原來 Java 文檔是來自這些註釋。難怪這些註釋叫做文檔註釋呢！不過，是什麼工具把這些註釋變成文檔的呢？
是該請出 javadoc 的時候了。在 JDK 的 bin 目錄下你可以找到 javadoc，如果是 Windows 下的 JDK，它的文件名爲 javadoc.exe。使用 javdoc 編譯 .java 源文件時，它會讀出 .java 源文件中的文檔註釋，並按照一定的規則與 Java 源程序一起進行編譯，生成文檔。
介紹 javadoc 的編譯命令之前，還是先了解一下文檔註釋的格式吧。不過爲了能夠編譯下面提到的若干例子，這裏先介紹一條 javadoc 命令：
javadoc -d 文檔存放目錄 -author -version 源文件名.java
這條命令編譯一個名爲 “源文件名.java”的 java 源文件，並將生成的文檔存放在“文檔存放目錄”指定的目錄下，生成的文檔中 index.html 就是文檔的首頁。-author 和 -version 兩上選項可以省略。
二. 文檔註釋的格式
文檔註釋可以用於對類、屬性、方法等進行說明。寫文檔註釋時除了需要使用 /** .... */ 限定之外，還需要注意註釋內部的一些細節問題。
1. 文檔和文檔註釋的格式化
生成的文檔是 HTML 格式，而這些 HTML 格式的標識符並不是 javadoc 加的，而是我們在寫註釋的時候寫上去的。比如，需要換行時，不是敲入一個回車符，而是寫入 ＜br＞，如果要分段，就應該在段前寫入 ＜p＞。
因此，格式化文檔，就是在文檔註釋中添加相應的 HTML 標識。
文檔註釋的正文並不是直接複製到輸出文件 (文檔的 HTML 文件)，而是讀取每一行後，刪掉前導的 * 號及 * 號以前的空格，再輸入到文檔的。如
| /** * This is first line. ＜br＞ ***** This is second line. ＜br＞ This is third line. */ |
編譯輸出後的 HTML 源碼則是
| This is first line. ＜br＞ This is second line. ＜br＞ This is third line. |
前導的 * 號允許連續使用多個，其效果和使用一個 * 號一樣，但多個 * 號前不能有其它字符分隔，否則分隔符及後面的 * 號都將作爲文檔的內容。* 號在這裏是作爲左邊界使用，如上例的第一行和第二行；如果沒有前導的 * 號，則邊界從第一個有效字符開始，而不包括前面的空格，如上例第三行。
還有一點需要說明，文檔註釋只說明緊接其後的類、屬性或者方法。如下例：
| /** comment for class */ public class Test { /** comment for a attribute */ int number; /** comment for a method */ public void myMethod() { ...... } ...... } |
上例中的三處註釋就是分別對類、屬性和方法的文檔註釋。它們生成的文檔分別是說明緊接其後的類、屬性、方法的。“緊接”二字尤其重要，如果忽略了這一點，就很可能造成生成的文檔錯誤。如
| import java.lang.*; /** commnet for class */ public class Test { ...... } // 此例爲正確的例子 |
這個文檔註釋將生成正確的文檔。但只需要改變其中兩行的位置，變成下例，就會出錯：
| /** commnet for class */ import java.lang.*; public class Test { ...... } // 此例爲錯誤的例子 |
這個例子只把上例的 import 語句和文檔註釋部分交換了位置，結果卻大不相同——生成的文檔中根本就找不到上述註釋的內容了。原因何在？
“/** commnet for class */”是對 class Test 的說明，把它放在“public class Test { ...... }”之前時，其後緊接着 class Test，符合規則，所以生成的文檔正確。但是把它和“import java.lang.*;”調換了位置後，其後緊接的就是不 class Test 了，而是一個 import 語句。由於文檔註釋只能說明類、屬性和方法，import 語句不在此列，所以這個文檔註釋就被當作錯誤說明省略掉了
2. 文檔註釋的三部分
根據在文檔中顯示的效果，文檔註釋分爲三部分。先舉例如下，以便說明。
| /**
* show 方法的簡述. * ＜p＞show 方法的詳細說明第一行＜br＞ * show 方法的詳細說明第二行 * @param b true 表示顯示，false 表示隱藏 * @return 沒有返回值 */ public void show(boolean b) { frame.show(b); } |
第一部分是簡述。文檔中，對於屬性和方法都是先有一個列表，然後纔在後面一個一個的詳細的說明。列表中屬性名或者方法名後面那段說明就是簡述。如下圖中被紅框框選的部分：
 |
簡述部分寫在一段文檔註釋的最前面，第一個點號 (.) 之前 (包括點號)。換句話說，就是用第一個點號分隔文檔註釋，之前是簡述，之後是第二部分和第三部分。如上例中的 “* show 方法的簡述.”。
有時，即使正確地以一個點號作爲分隔，javadoc 仍然會出錯，把點號後面的部分也做爲了第一部分。爲了解決這個問題，我們可以使用一個 ＜p＞ 標誌將第二分部分開爲下一段，如上例的“* ＜p＞show 方法的詳細說明第一行 ....”。除此之外，我們也可以使用 ＜br＞ 來分隔。
第二部分是詳細說明部分。該部分對屬性或者方法進行詳細的說明，在格式上沒有什麼特殊的要求，可以包含若干個點號。它在文檔中的位置如下圖所示：
|
這部分文檔在上例中相應的代碼是：
| * show 方法的簡述.
* ＜p＞show 方法的詳細說明第一行＜br＞ * show 方法的詳細說明第二行 |
發現什麼了？對了，簡述也在其中。這一點要記住了，不要畫蛇添足——在詳細說明部分中再寫一次簡述哦！
第三部分是特殊說明部分。這部分包括版本說明、參數說明、返回值說明等。它在文檔中的位置：
|
第三部分在上例中相應的代碼是
| * @param b true 表示顯示，false 表示隱藏
* @return 沒有返回值 |
除了 @param 和 @return 之外，還有其它的一些特殊標記，分別用於對類、屬性和方法的說明……不要推我，我馬上就說。
三. 使用 javadoc 標記
javadoc 標記是插入文檔註釋中的特殊標記，它們用於標識代碼中的特殊引用。javadoc 標記由“@”及其後所跟的標記類型和專用註釋引用組成。記住了，三個部分——@、標記類型、專用註釋引用。不過我寧願把它分成兩部分：@ 和標記類型、專用註釋引用。雖然 @ 和 標記類型之間有時可以用空格符分隔，但是我寧願始終將它們緊挨着寫，以減少出錯機會。
javadoc 標記有如下一些：
| 標記 | 用於 | 作用 |
| @author | 對類的說明 | 標明開發該類模塊的作者 |
| @version | 對類的說明 | 標明該類模塊的版本 |
| @see | 對類、屬性、方法的說明 | 參考轉向，也就是相關主題 |
| @param | 對方法的說明 | 對方法中某參數的說明 |
| @return | 對方法的說明 | 對方法返回值的說明 |
| @exception | 對方法的說明 | 對方法可能拋出的異常進行說明 |
下面詳細說明各標記。
1. @see 的使用
@see 的句法有三種：
| @see 類名
@see #方法名或屬性名 @see 類名#方法名或屬性名 |
類名，可以根據需要只寫出類名 (如 String) 或者寫出類全名 (如 java.lang.String)。那麼什麼時候只需要寫出類名，什麼時候需要寫出類全名呢？
如果 java 源文件中的 import 語句包含了的類，可以只寫出類名，如果沒有包含，則需要寫出類全名。java.lang 也已經默認被包含了。這和 javac 編譯 java 源文件時的規定一樣，所以可以簡單的用 javac 編譯來判斷，源程序中 javac 能找到的類，javadoc 也一定能找到；javac 找不到的類，javadoc 也找不到，這就需要使用類全名了。
方法名或者屬性名，如果是屬性名，則只需要寫出屬性名即可；如果是方法名，則需要寫出方法名以及參數類型，沒有參數的方法，需要寫出一對括號。如
| 成員類型 | 成員名稱及參數 | @see 句法 |
| 屬性 | number | @see number |
| 屬性 | count | @see count |
| 方法 | count() | @see count() |
| 方法 | show(boolean b) | @see show(boolean) |
| 方法 | main(String[] args) | @see main(String[]) |
有時也可以偷懶：假如上例中，沒有 count 這一屬性，那麼參考方法 count() 就可以簡寫成 @see count。不過，爲了安全起見，還是寫全 @see count() 比較好。
@see 的第二個句法和第三個句法都是轉向方法或者屬性的參考，它們有什麼區別呢？
第二個句法中沒有指出類名，則默認爲當前類。所以它定義的參考，都轉向本類中的屬性或者方法。而第三個句法中指出了類名，則還可以轉向其它類的屬性或者方法。
關於 @see 標記，我們舉個例說明。由於 @see 在對類說明、對屬性說明、對方法說明時用法都一樣，所以這裏只以對類說明爲例。
| /**
* @see String * @see java.lang.StringBuffer * @see #str * @see #str() * @see #main(String[]) * @see Object#toString() */ public class TestJavaDoc { } |
生成的文檔的相關部分如下圖：
|
String 和 StringBuffer 都是在 java.lang 包中，由於這個包是默認導入了的，所以這兩個類可以直接寫類名，也可以寫類全名。str、str() 爲同名屬性和方法，所以方法名需要用 () 區分。main 是帶參數的方法，所以在 () 中指明瞭參數類型。toString() 雖然在本類中也有 (從 Object 繼承的)，但我們是想參考 Object 類的 toString() 方法，所以使用了 Object#toString()。
奇怪的是，爲什麼其中只有 str、str() 和 main(String[]) 變成了鏈接呢？那是因爲編譯時沒有把 java.lang 包或者 Stirng、StringBuffer、Object 三個類的源文件一起加入編譯，所以，生成的文檔沒有關於那三個類的信息，也就不可以建立鏈接了。後面講解 javadoc 編譯命令的時候還會詳細說明。
上例中如果去把類中的 str 屬性去掉，那麼生成的文檔又會有什麼變化呢？你會發現，原來是 str, str()，而現在變成了 str(), str()，因爲 str 屬性已經沒有了，所以 str 也表示方法 str()。
2. 使用 @author、@version 說明類
這兩個標記分別用於指明類的作者和版本。缺省情況下 javadoc 將其忽略，但命令行開關 -author 和 -version 可以修改這個功能，使其包含的信息被輸出。這兩個標記的句法如下：
@author 作者名
@version 版本號
其中，@author 可以多次使用，以指明多個作者，生成的文檔中每個作者之間使用逗號 (,) 隔開。@version 也可以使用多次，只有第一次有效，生成的文檔中只會顯示第一次使用 @version 指明的版本號。如下例
| /**
* @author Fancy * @author Bird * @version Version 1.00 * @version Version 2.00 */ public class TestJavaDoc { } |
生成文檔的相關部分如圖：
|
從生成文檔的圖示中可以看出，兩個 @author 語句都被編譯，在文檔中生成了作者列表。而兩個 @version 語句中只有第一句被編譯了，只生成了一個版本號。
從圖上看，作者列表是以逗號分隔的，如果我想分行顯示怎麼辦？另外，如果我想顯示兩個以上的版本號又該怎麼辦？
——我們可以將上述兩條 @author 語句合爲一句，把兩個 @version 語句也合爲一句：
@author Fancy＜br＞Bird
@version Version 1.00＜br＞Version 2.00
結果如圖：
|
我們這樣做即達到了目的，又沒有破壞規則。@author 之後的作者名和 @version 之後的版本號都可以是用戶自己定義的任何 HTML 格式，所以我們可以使用 ＜br＞ 標記將其分行顯示。同時，在一個 @version 中指明兩個用 ＜br＞ 分隔的版本號，也沒有破壞只顯示第一個 @version 內容的規則。
3. 使用 @param、@return 和 @exception 說明方法
這三個標記都是隻用於方法的。@param 描述方法的參數，@return 描述方法的返回值，@exception 描述方法可能拋出的異常。它們的句法如下：
@param 參數名 參數說明
@return 返回值說明
@exception 異常類名 說明
每一個 @param 只能描述方法的一個參數，所以，如果方法需要多個參數，就需要多次使用 @param 來描述。
一個方法中只能用一個 @return，如果文檔說明中列了多個 @return，則 javadoc 編譯時會發出警告，且只有第一個 @return 在生成的文檔中有效。
方法可能拋出的異常應當用 @exception 描述。由於一個方法可能拋出多個異常，所以可以有多個 @exception。每個 @exception 後面應有簡述的異常類名，說明中應指出拋出異常的原因。需要注意的是，異常類名應該根據源文件的 import 語句確定是寫出類名還是類全名。 示例如下：
| public class TestJavaDoc {
/** * @param n a switch * @param b excrescent parameter * @return true or false * @return excrescent return * @exception java.lang.Exception throw when switch is 1 * @exception NullPointerException throw when parameter n is null */ public boolean fun(Integer n) throws Exception { switch (n.intValue()) { case 0: break; case 1: throw new Exception("Test Only"); default: return false; } return true; } } |
使用 javadoc 編譯生成的文檔相關部分如下圖：
|
可以看到，上例中 @param b excrescent parameter 一句是多餘的，因爲參數只是一個 n，並沒有一個 b 但是 javadoc 編譯時並沒有檢查。因此，寫文檔註釋時一定要正確匹配參數表與方法中正式參數表的項目。如果方法參數表中的參數是 a，文檔中卻給出對參數 x 的解釋，或者再多出一個參數 i，就會讓人摸不着頭腦了。@exceptin 也是一樣。
上例程序中並沒有拋出一個 NullPointerException，但是文檔註釋中爲什麼要寫上這麼一句呢，難道又是爲了演示？這不是爲了演示描述多餘的異常也能通過編譯，而是爲了說明寫異常說明時應考運行時 (RunTime) 異常的可能性。上例程序中，如果參數 n 是給的一個空值 (null)，那麼程序會在運行的時候拋出一個 NullPointerException，因此，在文檔註釋中添加了對 NullPointerException 的說明。
上例中的 @return 語句有兩個，但是根據規則，同一個方法中，只有第一個 @return 有效，其餘的會被 javadoc 忽略。所以生成的文檔中沒有出現第二個 @return 的描述。
講到這裏，該怎麼寫文檔註釋你應該已經清楚了，下面就開始講解 javadoc 的常用命令。
四. javadoc 命令
運行 javadoc -help 可以看到 javadoc 的用法，這裏列舉常用參數如下：
用法：
javadoc [options] [packagenames] [sourcefiles]
選項：
-public 僅顯示 public 類和成員
-protected 顯示 protected/public 類和成員 (缺省)
-package 顯示 package/protected/public 類和成員
-private 顯示所有類和成員
-d ＜directory＞ 輸出文件的目標目錄
-version 包含 @version 段
-author 包含 @author 段
-splitindex 將索引分爲每個字母對應一個文件
-windowtitle ＜text＞ 文檔的瀏覽器窗口標題
javadoc 編譯文檔時可以給定包列表，也可以給出源程序文件列表。例如在 CLASSPATH 下有兩個包若干類如下：
fancy.Editor
fancy.Test
fancy.editor.ECommand
fancy.editor.EDocument
fancy.editor.EView
這裏有兩個包 (fancy 和 fancy.editor) 和 5 個類。那麼編譯時 (Windows 環境) 可以使用如下 javadoc 命令：
javadoc fancy\Test.java fancy\Editor.java fancy\editor\ECommand.java fancy\editor\EDocument.java fancy\editor\EView.java
這是給出 java 源文件作爲編譯參數的方法，注意命令中指出的是文件路徑，應該根據實際情況改變。也可以是給出包名作爲編譯參數，如：
javadoc fancy fancy.editor
用瀏覽器打開生成文檔的 index.html 文件即可發現兩種方式編譯結果的不同，如下圖：
|
用第二條命令生成的文檔被框架分成了三部分：包列表、類列表和類說明。在包列表中選擇了某個包之後，類列表中就會列出該包中的所有類；在類列表中選擇了某個類之後，類說明部分就會顯示出該類的詳細文檔。而用第一條命令生成的文檔只有兩部分，類列表和類說明，沒有包列表。這就是兩種方式生成文檔的最大區別了。
兩種方式編譯還有一點不同，
下面再來細說選項。
-public、-protected、-package、-private 四個選項，只需要任選其一即可。它們指定的顯示類成員的程度。它們顯示的成員多少是一個包含的關係，如下表：
-private (顯示所有類和成員)
-package (顯示 package/protected/public 類和成員)
-protected (顯示 protected/public 類和成員)
-public (僅顯示 public 類和成員)
-d 選項允許你定義輸出目錄。如果不用 -d 定義輸出目錄，生成的文檔文件會放在當前目錄下。-d 選項的用法是
-d 目錄名
目錄名爲必填項，也就是說，如果你使用了 -d 參數，就一定要爲它指定一個目錄。這個目錄必須已經存在了，如果還不存在，請在運行 javadoc 之前創建該目錄。
-version 和 -author 用於控制生成文檔時是否生成 @version 和 @author 指定的內容。不加這兩個參數的情況下，生成的文檔中不包含版本和作者信息。
-splitindex 選項將索引分爲每個字母對應一個文件。默認情況下，索引文件只有一個，且該文件中包含所有索引內容。當然生成文檔內容不多的時候，這樣做非常合適，但是，如果文檔內容非常多的時候，這個索引文件將包含非常多的內容，顯得過於龐大。使用 -splitindex 會把索引文件按各索引項的第一個字母進行分類，每個字母對應一個文件。這樣，就減輕了一個索引文件的負擔。
-windowtitle 選項爲文檔指定一個標題，該標題會顯示在窗口的標題欄上。如果不指定該標題，而默認的文檔標題爲“生成的文檔（無標題）”。該選項的用法是：
-windowtitle 標題
標題是一串沒有包含空格的文本，因爲空格符是用於分隔各參數的，所以不能包含空格。同 -d 類似，如果指定了 -windowtitle 選項，則必須指定標題文本。
到此爲止，Java 文檔和 javadoc 就介紹完了。javadoc 真的能讓我們在 Java 註釋上做文章——生成開發文