2.2 Java的程序注釋

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

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

javadoc輸出的是一個HTML文件，可用Web瀏覽器查看。該工具允許創(chuàng)建和管理單個源文件，并生成有用的文檔。由于有了javadoc，所以能夠用標準的方法創(chuàng)建文檔。由于使用它非常方便，所以能輕松獲得所有Java庫的文檔。

1．具體語法

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

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

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

注意，javadoc只能為public（公共）和protected（受保護）成員處理注釋文檔。private（私有）和“友好”（詳見第3 章）成員的注釋會被忽略，看不到任何輸出（也可以用private標記包括private成員）。這樣做是有道理的，因為只有public和protected成員才可在文件之外使用，這是客戶程序員所希望的。然而，所有類注釋都會包含到輸出結(jié)果里。

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

2．嵌入HTML

javadoc將最終生成HTML文檔，這便于使用戶能夠充分利用HTML的性能。當然，最后的目的是格式化代碼，如下所示。

            /**
            *
            * System.out.println("Hello World!");
            *
            */
            /**
            *甚至可以插入一個列表：
            *
            *項目一
            *項目二
            *項目三
            *
            */

注意，在文檔注釋中，位于一行最開頭的星號會被javadoc丟棄，同時被丟棄的還有之前的空格。javadoc會對所有內(nèi)容進行格式化，使其與標準的文檔外觀相符。不要將這樣的標題當做嵌入HTML使用，因為javadoc會插入自己的標題，用戶給出的標題會與之沖突。所有類型的注釋文檔：類、變量和方法，都支持嵌入HTML文檔。

3．@see：引用其他類

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

@see類名

@see完整類名

每一格式都會在生成的文檔里自動加入一個超鏈接的“See Also”（參見）條目。注意javadoc不會檢查指定的超鏈接，不會驗證它們是否有效。

4．類文檔標記

隨同嵌入HTML和@see引用，類文檔還可以包括用于版本信息及作者姓名的標記。類文檔也可以用于接口為目的（后面會講到）。

（1）@version

格式如下：

@version版本信息

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

（2）@author

格式如下：

@author作者信息

其中，作者信息可以包含姓名、電子郵件地址或其他任何資料。如果在javadoc命令行使用了author標記，就會專門從生成的HTML文檔里提取出作者信息?？蔀橐幌盗凶髡呤褂枚鄠€這樣的標記，但它們必須連續(xù)放置。全部作者信息會一起存入最終HTML代碼的單獨一個段落里。

5．變量文檔標記

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

6．方法文檔標記

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

（1）@param

格式如下：

@param參數(shù)名 說明

其中，參數(shù)名指參數(shù)列表內(nèi)的標識符，而說明代表一些可延續(xù)到后續(xù)行內(nèi)的說明文字。一旦遇到一個新文檔標記，就認為前一個說明結(jié)束。可使用任意數(shù)量的說明。

（2）@return

格式如下：

@return說明

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

（3）@exception

有關(guān)異常（exception）的詳細情況，會在以后的章節(jié)中具體講述。簡單來說，它們是一些特殊的對象，若某個方法失敗，就可將它們“拋出”。調(diào)用一個方法時，盡管只有一個異常對象出現(xiàn)，但一些特殊的方法也許能產(chǎn)生任意數(shù)量的、不同類型的異常。所有這些異常都需要說明。所以，異常標記的格式如下：

@exception完整類名 說明

其中，完整類名明確指定了一個違例類的名字，它是在其他某個地方定義好的。而說明（同樣可以延續(xù)到下面的行）告訴用戶為什么這種特殊類型的違例會在方法調(diào)用中出現(xiàn)。

（4）@deprecated

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