注釋和嵌入文檔(Comments and embedded documentation)
Java里有兩種類型的注釋。第一種是傳統(tǒng)的、C語言風格的注釋，是從C++繼承而來的。
注釋用一個“/*”起頭，隨后是注釋內(nèi)容，并可跨越多行，最后用一個“*/”結(jié)束。
/* 這是
* 一段注釋，
* 它跨越了多個行
*/
但請記住，進行編譯時，/*和*/之間的所有東西都會被忽略，所以上述注釋與下面這段注釋并沒有什么不同：
/* 這是一段注釋，
它跨越了多個行 */
第二種類型的注釋也起源于C++。這種注釋叫作“單行注釋”，以一個“//”起頭，表示這一行的所有內(nèi)容都是注釋。這種類型的注釋更常用，因為它書寫時更方便。沒有必要在鍵盤上尋找“/”，再尋找“*”（只需按同樣的鍵兩次），而且不必在注釋結(jié)尾時加一個結(jié)束標記。下面便是這類注釋的一個例子：
// 這是一條單行注釋
注釋文檔
用于提取注釋的工具叫作javadoc。它采用了部分來自Java編譯器的技術(shù)，查找我們置入程序的特殊注釋標記。它不僅提取由這些標記指示的信息，也將毗鄰注釋的類名或方法名提取出來。這樣一來，我們就可用最輕的工作量，生成十分專業(yè)的程序文檔。
javadoc輸出的是一個HTML文件，可用自己的Web瀏覽器查看。該工具允許我們創(chuàng)建和管理單個源文件，并生動生成有用的文檔。
所有javadoc命令都只能出現(xiàn)于“/**”注釋中，注釋結(jié)束于“*/”。
有兩種方式來使用javadoc：
嵌入HTML，
使用?“文檔標記”（Doc tags）, 文檔標記是以“@”開頭的命令，置于注釋行的起始處（但前導的“*”會被忽略）。
有三種類型的注釋文檔，它們對應于位于注釋后面的元素：類、變量或者方法。
類注釋在一個類定義之前；
變量注釋在變量定義之前；
方法注釋在方法定義的前面。
如下例所示：
/** 一個類注釋 */
public class docTest {
/** 一個變量注釋 */
public int i;
/** 一個方法注釋 */
public void f() {}
}
注意javadoc只能為public（公共）和protected（受保護）成員處理注釋文檔。“private”（私有）和“友好”（詳見5章）成員的注釋會被忽略，我們看不到任何輸出（也可以用-private標記包括private成員）。這樣做的理由是，因為只有public和protected成員才可在文件之外使用。所有類注釋都會包含到輸出結(jié)果里。
嵌入HTML
javadoc將HTML命令傳遞給最終生成的HTML文檔。這便能充分利用HTML。這樣做的最終目的還是格式化代碼。
見下例：
/**
* <pre>
* System.out.println(new Date());
* </pre>
*/
也可以像在Web文檔里使用HTML一樣，對普通文本進行格式化，使其更具條理、更加美觀：
/**
* 您<em>甚至</em>可以插入一個列表：
* <ol>
* <li> 項目一
* <li> 項目二
* <li> 項目三
* </ol>
*/
注意在文檔注釋中，每行最開頭的星號會被javadoc忽略。同時忽略的還有前方空格（leading spaces）。javadoc會對所有內(nèi)容進行格式化，使其與標準的文檔外觀相符。不要將<h1>或<hr>這樣的標題當作嵌入HTML使用，因為javadoc會插入自己的標題。
所有類型的注釋文檔——類、變量和方法——都支持嵌入HTML。
@see：引用其他類
所有三種類型的注釋文檔都可包含@see標記，它允許我們引用其他類里的文檔。對于這個標記，javadoc會生成相應的HTML，將其直接鏈接到其他文檔。格式如下：
@see 類名
@see 完整類名
@see 完整類名#方法名
每一格式都會在生成的文檔里自動加入一個超鏈接的“See Also”（參見）條目。注意javadoc不會檢查我們指定的超鏈接，不會驗證它們是否有效。
類文檔標記
隨同嵌入HTML和@see引用，類文檔還可以包括用于版本信息以及作者姓名的標記。類文檔亦可用于“接口”。
@version
格式如下：
@version 版本信息
其中，“版本信息”代表任何適合作為版本說明的資料。在javadoc命令行使用“-version”標記會從生成的HTML文檔里提取出版本信息。
@author
格式如下：
@author 作者信息
其中，“作者信息”包括姓名、電子函件地址或者其他任何適合的資料。在javadoc命令行使用了“-author”標記會專門從生成的HTML文檔里提取出作者信息。
可為一系列作者使用多個這樣的標記，但這些必須連續(xù)放置。全部作者信息會一起存入最終HTML代碼的單獨一個段落里。
變量文檔標記
變量文檔只能包括嵌入的HTML以及@see引用。
方法文檔標記
除嵌入HTML和@see引用之外，方法還允許使用針對參數(shù)、返回值以及違例的文檔標記。
@param
格式如下：
@param 參數(shù)名 說明
其中，“參數(shù)名”是指參數(shù)列表內(nèi)的標識符，而“說明”代表一些可延續(xù)到后續(xù)行內(nèi)的說明文字。一旦遇到一個新文檔標記，就認為前一個說明結(jié)束?？墒褂萌我鈹?shù)量的說明，每個參數(shù)一個。
@return
格式如下：
@return 說明
其中，“說明”是指返回值的含義，可延續(xù)到后面的行內(nèi)。
@exception
有關(guān)“異?！保‥xception）的詳細情況。調(diào)用一個方法時，盡管只有一個異常對象出現(xiàn)，但一些特殊的方法也許能產(chǎn)生任意數(shù)量且不同類型的異常。所有的異常都需要說明。異常標記的格式如下：
@exception 完整類名 說明
其中，“完整類名”明確指定了一個違例類的名字，可以是在其他某個地方定義好的。而“說明”則解釋為什么這個異常會在方法調(diào)用中出現(xiàn)。
@deprecated
該標記用于指出一些舊功能已由改進過的新功能取代。該標記的作用是建議用戶不必再使用一種特定的功能，因為未來改版時可能摒棄這一功能。若將一個方法標記為@deprecated，則使用該方法時會收到編譯器的警告。
文檔示例
下面還是我們的第一個Java程序，只不過已加入了完整的文檔注釋：
//: object/HelloDate.java
import java.util.*;
/** The first Thinking in Java example program.
* Displays a string and today’s date.
* @author Bruce Eckel
* @author www.MindView.net
* @version 4.0
*/
public class HelloDate {
/** Entry point to class & application.
* @param args array of string arguments
* @throws exceptions No exceptions thrown
*/
public static void main(String[] args) {
System.out.println("Hello, it’s: ");
System.out.println(new Date());
}
} /* Output: (55% match)
Hello, it’s:
Wed Oct 05 14:39:36 MDT 2005
