# 2.8 注釋和嵌入文檔 (2)8 注釋和嵌入文檔 Java里有兩種類型的注釋。第一種是傳統的、C語言風格的注釋，是從C++繼承而來的。這些注釋用一個 `/*` 起頭，隨后是注釋內容，并可跨越多行，最后用一個`*/`結束。注意許多程序員在連續注釋內容的每一行都用一個 `*` 開頭，所以經常能看到象下面這樣的內容： ``` /* 這是 * 一段注釋， * 它跨越了多個行 */ ``` 但請記住，進行編譯時，`/*`和`*/`之間的所有東西都會被忽略，所以上述注釋與下面這段注釋并沒有什么不同： ``` /* 這是一段注釋， 它跨越了多個行 */ ``` 第二種類型的注釋也起源于C++。這種注釋叫作“單行注釋”，以一個 `//` 起頭，表示這一行的所有內容都是注釋。這種類型的注釋更常用，因為它書寫時更方便。沒有必要在鍵盤上尋找 `/` ，再尋找 `*` （只需按同樣的鍵兩次），而且不必在注釋結尾時加一個結束標記。下面便是這類注釋的一個例子： ``` // 這是一條單行注釋 ``` ## 2.8.1 注釋文檔 對于Java語言，最體貼的一項設計就是它并沒有打算讓人們為了寫程序而寫程序——人們也需要考慮程序的文檔化問題。對于程序的文檔化，最大的問題莫過于對文檔的維護。若文檔與代碼分離，那么每次改變代碼后都要改變文檔，這無疑會變成相當麻煩的一件事情。解決的方法看起來似乎很簡單：將代碼同文檔“鏈接”起來。為達到這個目的，最簡單的方法是將所有內容都置于同一個文件。然而，為使一切都整齊劃一，還必須使用一種特殊的注釋語法，以便標記出特殊的文檔；另外還需要一個工具，用于提取這些注釋，并按有價值的形式將其展現出來。這些都是Java必須做到的。 用于提取注釋的工具叫作`javadoc`。它采用了部分來自Java編譯器的技術，查找我們置入程序的特殊注釋標記。它不僅提取由這些標記指示的信息，也將毗鄰注釋的類名或方法名提取出來。這樣一來，我們就可用最輕的工作量，生成十分專業的程序文檔。 `javadoc`輸出的是一個HTML文件，可用自己的Web瀏覽器查看。該工具允許我們創建和管理單個源文件，并生動生成有用的文檔。由于有了`javadoc`，所以我們能夠用標準的方法創建文檔。而且由于它非常方便，所以我們能輕松獲得所有Java庫的文檔。 ## 2.8.2 具體語法 所有javadoc命令都只能出現于 `/**` 注釋中。但和平常一樣，注釋結束于一個 `*/` 。主要通過兩種方式來使用`javadoc`：嵌入的HTML，或使用“文檔標記”。其中，“文檔標記”（Doc tags）是一些以`@`開頭的命令，置于注釋行的起始處（但前導的`*`會被忽略）。 有三種類型的注釋文檔，它們對應于位于注釋后面的元素：類、變量或者方法。也就是說，一個類注釋正好位于一個類定義之前；變量注釋正好位于變量定義之前；而一個方法定義正好位于一個方法定義的前面。如下面這個簡單的例子所示： ``` /** 一個類注釋 */ public class docTest { /** 一個變量注釋 */ public int i; /** 一個方法注釋 */ public void f() {} } ``` 注意`javadoc`只能為`public`（公共）和`protected`（受保護）成員處理注釋文檔。`private`（私有）和“友好”（詳見5章）成員的注釋會被忽略，我們看不到任何輸出（也可以用`-private`標記包括`private`成員）。這樣做是有道理的，因為只有`public`和`protected`成員才可在文件之外使用，這是客戶程序員的希望。然而，所有類注釋都會包含到輸出結果里。 上述代碼的輸出是一個HTML文件，它與其他Java文檔具有相同的標準格式。因此，用戶會非常熟悉這種格式，可在您設計的類中方便地“漫游”。設計程序時，請務必考慮輸入上述代碼，用`javadoc`處理一下，觀看最終HTML文件的效果如何。 ## 2.8.3 嵌入HTML `javadoc`將HTML命令傳遞給最終生成的HTML文檔。這便使我們能夠充分利用HTML的巨大威力。當然，我們的最終動機是格式化代碼，不是為了嘩眾取寵。下面列出一個例子： ``` /** * <pre> * System.out.println(new Date()); * </pre> */ ``` 亦可象在其他Web文檔里那樣運用HTML，對普通文本進行格式化，使其更具條理、更加美觀： ``` /** * 您<em>甚至</em>可以插入一個列表： * <ol> * <li> 項目一 * <li> 項目二 * <li> 項目三 * </ol> */ ``` 注意在文檔注釋中，位于一行最開頭的星號會被`javadoc`丟棄。同時丟棄的還有前導空格。`javadoc` 會對所有內容進行格式化，使其與標準的文檔外觀相符。不要將`<h1>`或`<hr>`這樣的標題當作嵌入HTML使用，因為`javadoc`會插入自己的標題，我們給出的標題會與之沖撞。 所有類型的注釋文檔——類、變量和方法——都支持嵌入HTML。 ## 2.8.4 `@see`：引用其他類 所有三種類型的注釋文檔都可包含`@see`標記，它允許我們引用其他類里的文檔。對于這個標記，`javadoc`會生成相應的HTML，將其直接鏈接到其他文檔。格式如下： ``` @see 類名 @see 完整類名 @see 完整類名#方法名 ``` 每一格式都會在生成的文檔里自動加入一個超鏈接的“See Also”（參見）條目。注意`javadoc`不會檢查我們指定的超鏈接，不會驗證它們是否有效。 ## 2.8.5 類文檔標記 隨同嵌入HTML和`@se`e引用，類文檔還可以包括用于版本信息以及作者姓名的標記。類文檔亦可用于“接口”目的（本書后面會詳細解釋）。 **1. `@version`** 格式如下： ``` @version 版本信息 ``` 其中，“版本信息”代表任何適合作為版本說明的資料。若在`javadoc`命令行使用了`-version`標記，就會從生成的HTML文檔里提取出版本信息。 **2. `@author`** 格式如下： ``` @author 作者信息 ``` 其中，“作者信息”包括您的姓名、電子函件地址或者其他任何適宜的資料。若在`javadoc`命令行使用了`-author`標記，就會專門從生成的HTML文檔里提取出作者信息。 可為一系列作者使用多個這樣的標記，但它們必須連續放置。全部作者信息會一起存入最終HTML代碼的單獨一個段落里。 ## 2.8.6 變量文檔標記 變量文檔只能包括嵌入的HTML以及`@see`引用。 ## 2.8.7 方法文檔標記 除嵌入HTML和`@see`引用之外，方法還允許使用針對參數、返回值以及異常的文檔標記。 **1. `@param`** 格式如下： ``` @param 參數名 說明 ``` 其中，“參數名”是指參數列表內的標識符，而“說明”代表一些可延續到后續行內的說明文字。一旦遇到一個新文檔標記，就認為前一個說明結束。可使用任意數量的說明，每個參數一個。 **2. `@return`** 格式如下： ``` @return 說明 ``` 其中，“說明”是指返回值的含義。它可延續到后面的行內。 **3. `@exception`** 有關“異常”（`Exception`）的詳細情況，我們會在第9章講述。簡言之，它們是一些特殊的對象，若某個方法失敗，就可將它們“扔出”對象。調用一個方法時，盡管只有一個異常對象出現，但一些特殊的方法也許能產生任意數量的、不同類型的異常。所有這些異常都需要說明。所以，異常標記的格式如下： ``` @exception 完整類名 說明 ``` 其中，“完整類名”明確指定了一個異常類的名字，它是在其他某個地方定義好的。而“說明”（同樣可以延續到下面的行）告訴我們為什么這種特殊類型的異常會在方法調用中出現。 **4. `@deprecated`** 這是Java 1.1的新特性。該標記用于指出一些舊功能已由改進過的新功能取代。該標記的作用是建議用戶不必再使用一種特定的功能，因為未來改版時可能摒棄這一功能。若將一個方法標記為`@deprecated`，則使用該方法時會收到編譯器的警告。 ## 2.8.8 文檔示例 下面還是我們的第一個Java程序，只不過已加入了完整的文檔注釋： 92頁程序 第一行： ``` //: Property.java ``` 采用了我自己的方法：將一個`:`作為特殊的記號，指出這是包含了源文件名字的一個注釋行。最后一行也用這樣的一條注釋結尾，它標志著源代碼清單的結束。這樣一來，可將代碼從本書的正文中方便地提取出來，并用一個編譯器檢查。這方面的細節在第17章講述。