2.8 注釋和嵌入文檔

2.8 注釋和嵌入文檔

Java里有兩種類型的注釋。第一種是傳統(tǒng)的、C語言風(fēng)格的注釋，是從C++繼承而來的。這些注釋用一個(gè) “/*” 起頭，隨后是注釋內(nèi)容，并可跨越多行，最后用一個(gè)“*/”結(jié)束。注意許多程序員在連續(xù)注釋內(nèi)容的每一行都用一個(gè) “*” 開頭，所以經(jīng)常能看到象下面這樣的內(nèi)容：

/* 這是
* 一段注釋，
* 它跨越了多個(gè)行
*/

但請記住，進(jìn)行編譯時(shí)，/和/之間的所有東西都會(huì)被忽略，所以上述注釋與下面這段注釋并沒有什么不同：

/* 這是一段注釋，
它跨越了多個(gè)行 */

第二種類型的注釋也起源于C++。這種注釋叫作“單行注釋”，以一個(gè) “//” 起頭，表示這一行的所有內(nèi)容都是注釋。這種類型的注釋更常用，因?yàn)樗鼤鴮憰r(shí)更方便。沒有必要在鍵盤上尋找 “/” ，再尋找 “*” （只需按同樣的鍵兩次），而且不必在注釋結(jié)尾時(shí)加一個(gè)結(jié)束標(biāo)記。下面便是這類注釋的一個(gè)例子：

// 這是一條單行注釋

2.8.1 注釋文檔

對于Java語言，最體貼的一項(xiàng)設(shè)計(jì)就是它并沒有打算讓人們?yōu)榱藢懗绦蚨鴮懗绦颉藗円残枰紤]程序的文檔化問題。對于程序的文檔化，最大的問題莫過于對文檔的維護(hù)。若文檔與代碼分離，那么每次改變代碼后都要改變文檔，這無疑會(huì)變成相當(dāng)麻煩的一件事情。解決的方法看起來似乎很簡單：將代碼同文檔“鏈接”起來。為達(dá)到這個(gè)目的，最簡單的方法是將所有內(nèi)容都置于同一個(gè)文件。然而，為使一切都整齊劃一，還必須使用一種特殊的注釋語法，以便標(biāo)記出特殊的文檔；另外還需要一個(gè)工具，用于提取這些注釋，并按有價(jià)值的形式將其展現(xiàn)出來。這些都是Java必須做到的。

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

javadoc輸出的是一個(gè)HTML文件，可用自己的Web瀏覽器查看。該工具允許我們創(chuàng)建和管理單個(gè)源文件，并生動(dòng)生成有用的文檔。由于有了jvadoc，所以我們能夠用標(biāo)準(zhǔn)的方法創(chuàng)建文檔。而且由于它非常方便，所以我們能輕松獲得所有Java庫的文檔。

2.8.2 具體語法

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

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

/** 一個(gè)類注釋 */
public class docTest {
/** 一個(gè)變量注釋 */
public int i;
/** 一個(gè)方法注釋 */
public void f() {}
}

注意javadoc只能為public（公共）和protected（受保護(hù)）成員處理注釋文檔?！皃rivate”（私有）和“友好”（詳見5章）成員的注釋會(huì)被忽略，我們看不到任何輸出（也可以用-private標(biāo)記包括private成員）。這樣做是有道理的，因?yàn)橹挥衟ublic和protected成員才可在文件之外使用，這是客戶程序員的希望。然而，所有類注釋都會(huì)包含到輸出結(jié)果里。

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

2.8.3 嵌入HTML

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

/**
* <pre>
* System.out.println(new Date());
* </pre>
*/

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

/**
* 您<em>甚至</em>可以插入一個(gè)列表：
* <ol>
* <li> 項(xiàng)目一
* <li> 項(xiàng)目二
* <li> 項(xiàng)目三
* </ol>
*/

注意在文檔注釋中，位于一行最開頭的星號(hào)會(huì)被javadoc丟棄。同時(shí)丟棄的還有前導(dǎo)空格。javadoc 會(huì)對所有內(nèi)容進(jìn)行格式化，使其與標(biāo)準(zhǔn)的文檔外觀相符。不要將<h1>或<hr>這樣的標(biāo)題當(dāng)作嵌入HTML使用，因?yàn)閖avadoc會(huì)插入自己的標(biāo)題，我們給出的標(biāo)題會(huì)與之沖撞。

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

2.8.4 @see：引用其他類

所有三種類型的注釋文檔都可包含@see標(biāo)記，它允許我們引用其他類里的文檔。對于這個(gè)標(biāo)記，javadoc會(huì)生成相應(yīng)的HTML，將其直接鏈接到其他文檔。格式如下：

@see 類名
@see 完整類名
@see 完整類名#方法名

每一格式都會(huì)在生成的文檔里自動(dòng)加入一個(gè)超鏈接的“See Also”（參見）條目。注意javadoc不會(huì)檢查我們指定的超鏈接，不會(huì)驗(yàn)證它們是否有效。

2.8.5 類文檔標(biāo)記

隨同嵌入HTML和@see引用，類文檔還可以包括用于版本信息以及作者姓名的標(biāo)記。類文檔亦可用于“接口”目的（本書后面會(huì)詳細(xì)解釋）。

1. @version

格式如下：

@version 版本信息

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

2. @author

格式如下：

@author 作者信息

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

可為一系列作者使用多個(gè)這樣的標(biāo)記，但它們必須連續(xù)放置。全部作者信息會(huì)一起存入最終HTML代碼的單獨(dú)一個(gè)段落里。

2.8.6 變量文檔標(biāo)記

變量文檔只能包括嵌入的HTML以及@see引用。

2.8.7 方法文檔標(biāo)記

除嵌入HTML和@see引用之外，方法還允許使用針對參數(shù)、返回值以及違例的文檔標(biāo)記。

1. @param
格式如下：
@param 參數(shù)名 說明
其中，“參數(shù)名”是指參數(shù)列表內(nèi)的標(biāo)識(shí)符，而“說明”代表一些可延續(xù)到后續(xù)行內(nèi)的說明文字。一旦遇到一個(gè)新文檔標(biāo)記，就認(rèn)為前一個(gè)說明結(jié)束。可使用任意數(shù)量的說明，每個(gè)參數(shù)一個(gè)。

2. @return

格式如下：

@return 說明

其中，“說明”是指返回值的含義。它可延續(xù)到后面的行內(nèi)。

3. @exception

有關(guān)“違例”（Exception）的詳細(xì)情況，我們會(huì)在第9章講述。簡言之，它們是一些特殊的對象，若某個(gè)方法失敗，就可將它們“扔出”對象。調(diào)用一個(gè)方法時(shí)，盡管只有一個(gè)違例對象出現(xiàn)，但一些特殊的方法也許能產(chǎn)生任意數(shù)量的、不同類型的違例。所有這些違例都需要說明。所以，違例標(biāo)記的格式如下：

@exception 完整類名 說明

其中，“完整類名”明確指定了一個(gè)違例類的名字，它是在其他某個(gè)地方定義好的。而“說明”（同樣可以延續(xù)到下面的行）告訴我們?yōu)槭裁催@種特殊類型的違例會(huì)在方法調(diào)用中出現(xiàn)。

4. @deprecated

這是Java 1.1的新特性。該標(biāo)記用于指出一些舊功能已由改進(jìn)過的新功能取代。該標(biāo)記的作用是建議用戶不必再使用一種特定的功能，因?yàn)槲磥砀陌鏁r(shí)可能摒棄這一功能。若將一個(gè)方法標(biāo)記為@deprecated，則使用該方法時(shí)會(huì)收到編譯器的警告。

2.8.8 文檔示例

下面還是我們的第一個(gè)Java程序，只不過已加入了完整的文檔注釋：

92頁程序

第一行：

//: Property.java

采用了我自己的方法：將一個(gè)“:”作為特殊的記號(hào)，指出這是包含了源文件名字的一個(gè)注釋行。最后一行也用這樣的一條注釋結(jié)尾，它標(biāo)志著源代碼清單的結(jié)束。這樣一來，可將代碼從本書的正文中方便地提取出來，并用一個(gè)編譯器檢查。這方面的細(xì)節(jié)在第17章講述。