如果你讀過Java源碼，那你應該已經見到了源碼中優美的javadoc。在eclipse 中鼠標指向任何的公有方法都會顯示出詳細的描述，例如返回值、作用、異常類型等等。
本文主要來自《Thinking in java》的內容以及我在工作中寫javadoc的經驗。
三種類型的注釋文檔
注釋文檔有三種類型，分別對應於注釋位置后面的三種元素：類、域和方法。也就說類注釋正好位於類定義之前；域注釋位於域定義之前；方法注釋位於方法定義之前。如圖所示：
//: object/Documentation1.java
/** 類注釋 */
public class Documentation1 {
/** 域注釋 */
public int i;
/** 方法注釋 */
public void f() {}
} ///:~
注意，javadoc只能為public 和protected 成員進行文檔注釋。private 和包內可訪問成員的注釋會被忽略掉，所以在輸出結果中看不到他們。如果想在輸出結果中查看可以使用 -private 進行標記。這樣做是因為只有公用的和受保護的成員才能在文件之外被使用。上述代碼生成的HTML文檔可以在瀏覽器中查看。
嵌入式HTML
javadoc通過生成的html文檔傳送HTML命令，這使你能充分利用HTML。
/**
* <pre>
* System.out.println(new date())
* </pre>
*/
///:~
從上述注釋中我們也能看出，注釋是會進行輸出的，所以才會有System.out.println(new date()) 這個代碼。
還可以用HTML代碼格式化注釋：
/**
* You can <em>even</em> insert a list:
* <ol>
* <li> item one
* <li> item two
* <li> item three
* </ol>
*/
///:~
注意，每一行星號以及之后的空格內容不會輸出到文檔中，另外也不要在javadoc中使用標題標簽，例如<h1>或者<hr>。這是因為javadoc會插入自己的標題，而你的標題可能同它們發生沖突。
javadoc標簽
1.@see：引用其他類
@see 標簽允許用戶引用其他類的文檔。javadoc會在其生成的HTML文件中，通過@see 標簽鏈接到其他文檔。格式如下：
@see 類名
@see 完整類名
@see 完整類名#方法名
每一格式都會在生成的文檔里自動加入一個超鏈接的“See Also”（參見）條目。注意javadoc不會檢查我們指定的超鏈接，不會驗證它們是否有效。
2.{ @link package.class#member label }
該標簽與@see極其相似，只是它用於行內，並且是用“label” 作為超鏈接文本而不用“See Also”。
3.{ @docRoot }
該標簽產生到文檔根目錄的相對路徑，用於文檔樹頁面的顯示超鏈接
4.{ @inheritDoc }
該標簽從當前這個類的最直接的基類中繼承相關文檔到當前的文檔注釋中。
5. @version
格式如下：
@version version-information
其中，“version-information”代表任何適合作為版本說明的資料。若在javadoc命令行使用了“-version”標記，就會從生成的HTML文檔里提取出版本信息。
6. @author
格式如下：
@author author-information
其中，“author-information”包括您的姓名、電子函件地址或者其他任何適宜的資料。若在javadoc命令行使用了“-author”標記，就會專門從生成的HTML文檔里提取出作者信息。
可為一系列作者使用多個這樣的標記，但它們必須連續放置。全部作者信息會一起存入最終HTML代碼的單獨一個段落里。
7. @since
該標簽允許你指定程序代碼的最早使用版本，可以在HTML java文檔中看到它被用來指定所用的JDK版本的情況。
8. @param
該標簽用於方法文檔中，行使如下：
@param parameter-name description
其中，“parameter-name”是指參數列表內的標識符，而“description”代表一些可延續到后續行內的說明文字。一旦遇到一個新文檔標記，就認為前一個說明結束。可使用任意數量的說明，每個參數一個。
9. @return
格式如下：
@return description
其中，“description”是指返回值的含義。它可延續到后面的行內。
10. @throws
格式如下：
@throws fully-qualified-class-name description
其中fully-qualified-class-name description給出一個異常類的無歧義的名字，而該異常類在別處定義。description告訴你為什么此特殊類型的異常會在方法調用中出現。
11.@Deprecated
該標簽用於之處一些舊特性已由改進的新特性所取代，建議用戶不要再使用這些舊特性，因為在不久的將來它們很可能會被刪除。如果使用一個標記為@Deprecated的方法，則會引起編譯器發布警告。
源碼示例
我們看看JDK8中equals方法的注釋是怎樣寫的：
/**
* Compares this string to the specified object. The result is {@code
* true} if and only if the argument is not {@code null} and is a {@code
* String} object that represents the same sequence of characters as this
* object.
*
* @param anObject
* The object to compare this {@code String} against
*
* @return {@code true} if the given object represents a {@code String}
* equivalent to this string, {@code false} otherwise
*
* @see #compareTo(String)
* @see #equalsIgnoreCase(String)
*/
public boolean equals(Object anObject) {
if (this == anObject) {
return true;
}
if (anObject instanceof String) {
String anotherString = (String)anObject;
int n = value.length;
if (n == anotherString.value.length) {
char v1[] = value;
char v2[] = anotherString.value;
int i = 0;
while (n-- != 0) {
if (v1[i] != v2[i])
return false;
i++;
}
return true;
}
}
return false;
}
再來看下在eclipse中的顯示效果。
{@code } 前面沒有介紹過，實際顯示效果很容易看出來，就是把空格后的內容顯示成代碼的樣式。
寫出言簡意賅，便於維護的注釋需要長期的練習。除了工作中有意識的使用javadoc以外，閱讀源碼，模仿源碼注釋的寫法也是不錯的選擇。