JavaDoc，在 Java 的注釋上做文章(下)

2019-11-18 13:28:53

字體：大中小

來源：轉載

供稿：網友

　　2. 使用 @author、@version 說明類
　　這兩個標記分別用于指明類的作者和版本。缺省情況下 javadoc 將其忽略，但命令行開關 -author 和 -version 可以修改這個功能，使其包含的信息被輸出。這兩個標記的句法如下：
　　@author 作者名
　　@version 版本號
　　其中，@author 可以多次使用，以指明多個作者，生成的文檔中每個作者之間使用逗號 (,) 隔開。@version 也可以使用多次，只有第一次有效，生成的文檔中只會顯示第一次使用 @version 指明的版本號。如下例
　　/**
　　* @author Fancy
　　* @author Bird
　　* @version Version 1.00
　　* @version Version 2.00
　　*/
　　public class TestJavaDoc {
　　}
　　生成文檔的相關部分如圖：
　　　 JavaDoc，在 Java 的注釋上做文章(下)（圖一）

　　從生成文檔的圖示中可以看出，兩個 @author 語句都被編譯，在文檔中生成了作者列表。而兩個 @version 語句中只有第一句被編譯了，只生成了一個版本號。
　　從圖上看，作者列表是以逗號分隔的，假如我想分行顯示怎么辦？另外，假如我想顯示兩個以上的版本號又該怎么辦？
　　——我們可以將上述兩條 @author 語句合為一句，把兩個 @version 語句也合為一句：
　　@author Fancy
Bird
　　@version Version 1.00
Version 2.00
　　結果如圖：
　　　 JavaDoc，在 Java 的注釋上做文章(下)（圖二）

　　我們這樣做即達到了目的，又沒有破壞規則。@author 之后的作者名和 @version 之后的版本號都可以是用戶自己定義的任何 Html 格式，所以我們可以使用
標記將其分行顯示。同時，在一個 @version 中指明兩個用
分隔的版本號，也沒有破壞只顯示第一個 @version 內容的規則。
　　3. 使用 @param、@return 和 @exception 說明方法
　　這三個標記都是只用于方法的。@param 描述方法的參數，@return 描述方法的返回值，@exception 描述方法可能拋出的異常。它們的句法如下：
　　@param 參數名參數說明
　　@return 返回值說明
　　@exception 異常類名說明
　　每一個 @param 只能描述方法的一個參數，所以，假如方法需要多個參數，就需要多次使用 @param 來描述。
　　一個方法中只能用一個 @return，假如文檔說明中列了多個 @return，則 javadoc 編譯時會發出警告，且只有第一個 @return 在生成的文檔中有效。
　　方法可能拋出的異常應當用 @exception 描述。由于一個方法可能拋出多個異常，所以可以有多個 @exception。每個 @exception 后面應有簡述的異常類名，說明中應指出拋出異常的原因。需要注重的是，異常類名應該根據源文件的 import 語句確定是寫出類名還是類全名。　　示例如下：
　　public class TestJavaDoc {
　　/**
　　* @param n a switch
　　* @param b excrescent parameter
　　* @return true or false
　　* @return excrescent return
　　* @exception java.lang.Exception throw when switch is 1
　　* @exception NullPointerException throw when parameter n is null
　　*/
　　public boolean fun(Integer n) throws Exception {
　　switch (n.intValue()) {
　　case 0:
　　break;
　　case 1:
　　throw new Exception("Test Only");
　　default:
　　return false;
　　}
　　return true;
　　}
　　}
　　使用 javadoc 編譯生成的文檔相關部分如下圖：
　　　 JavaDoc，在 Java 的注釋上做文章(下)（圖三）

　　可以看到，上例中 @param b excrescent parameter 一句是多余的，因為參數只是一個 n，并沒有一個 b但是 javadoc 編譯時并沒有檢查。因此，寫文檔注釋時一定要正確匹配參數表與方法中正式參數表的項目。假如方法參數表中的參數是 a，文檔中卻給出對參數 x 的解釋，或者再多出一個參數 i，就會讓人摸不著頭腦了。@exceptin 也是一樣。
　　上例程序中并沒有拋出一個 NullPointerException，但是文檔注釋中為什么要寫上這么一句呢，難道又是為了演示？這不是為了演示描述多余的異常也能通過編譯，而是為了說明寫異常說明時應考運行時 (RunTime) 異常的可能性。上例程序中，假如參數 n 是給的一個空值 (null)，那么程序會在運行的時候拋出一個 NullPointerException，因此，在文檔注釋中添加了對 NullPointerException 的說明。
　　上例中的 @return 語句有兩個，但是根據規則，同一個方法中，只有第一個 @return 有效，其余的會被 javadoc 忽略。所以生成的文檔中沒有出現第二個 @return 的描述。
　　講到這里，該怎么寫文檔注釋你應該已經清楚了，下面就開始講解 javadoc 的常用命令。
　　四. javadoc 命令
　　運行 javadoc -help 可以看到 javadoc 的用法，這里列舉常用參數如下：
　　用法：
　　javadoc [options] [packagenames] [sourcefiles]
　　選項：
　　-public 僅顯示 public 類和成員
　　-PRotected 顯示 protected/public 類和成員 (缺省)
　　-package 顯示 package/protected/public 類和成員
　　-private 顯示所有類和成員
　　-d ＜Directory＞輸出文件的目標目錄
　　-version 包含 @version 段
　　-author 包含 @author 段
　　-splitindex 將索引分為每個字母對應一個文件
　　-windowtitle ＜text＞文檔的瀏覽器窗口標題
　　javadoc 編譯文檔時可以給定包列表，也可以給出源程序文件列表。例如在 CLASSPATH 下有兩個包若干類如下：
　　fancy.Editor
　　fancy.Test
　　fancy.editor.ECommand
　　fancy.editor.EDocument
　　fancy.editor.EView
　　這里有兩個包 (fancy 和 fancy.editor) 和 5 個類。那么編譯時 (Windows 環境) 可以使用如下 javadoc 命令：
　　javadoc fancy/Test.java fancy/Editor.java fancy/editor/ECommand.java fancy/editor/EDocument.java fancy/editor/EView.java
　　這是給出 java 源文件作為編譯參數的方法，注重命令中指出的是文件路徑，應該根據實際情況改變。也可以是給出包名作為編譯參數，如：
　　javadoc fancy fancy.editor
　　用瀏覽器打開生成文檔的 index.html 文件即可發現兩種方式編譯結果的不同，如下圖：
　　 JavaDoc，在 Java 的注釋上做文章(下)（圖四）

　　用第二條命令生成的文檔被框架分成了三部分：包列表、類列表和類說明。在包列表中選擇了某個包之后，類列表中就會列出該包中的所有類；在類列表中選擇了某個類之后，類說明部分就會顯示出該類的具體文檔。而用第一條命令生成的文檔只有兩部分，類列表和類說明，沒有包列表。這就是兩種方式生成文檔的最大區別了。
　　兩種方式編譯還有一點不同，
　　下面再來細說選項。
　　-public、-protected、-package、-private 四個選項，只需要任選其一即可。它們指定的顯示類成員的程度。它們顯示的成員多少是一個包含的關系，如下表：
　　-private (顯示所有類和成員)
　　-package (顯示 package/protected/public 類和成員)
　　-protected (顯示 protected/public 類和成員)
　　-public (僅顯示 public 類和成員)
　　-d 選項答應你定義輸出目錄。假如不用 -d 定義輸出目錄，生成的文檔文件會放在當前目錄下。-d 選項的用法是
　　-d 目錄名
　　目錄名為必填項，也就是說，假如你使用了 -d 參數，就一定要為它指定一個目錄。這個目錄必須已經存在了，假如還不存在，請在運行 javadoc 之前創建該目錄。
　　-version 和 -author 用于控制生成文檔時是否生成 @version 和 @author 指定的內容。不加這兩個參數的情況下，生成的文檔中不包含版本和作者信息。
　　-splitindex 選項將索引分為每個字母對應一個文件。默認情況下，索引文件只有一個，且該文件中包含所有索引內容。當然生成文檔內容不多的時候，這樣做非常合適，但是，假如文檔內容非常多的時候，這個索引文件將包含非常多的內容，顯得過于龐大。使用 -splitindex 會把索引文件按各索引項的第一個字母進行分類，每個字母對應一個文件。這樣，就減輕了一個索引文件的負擔。
　　-windowtitle 選項為文檔指定一個標題，該標題會顯示在窗口的標題欄上。假如不指定該標題，而默認的文檔標題為“生成的文檔（無標題）”。該選項的用法是：
　　-windowtitle 標題
　　標題是一串沒有包含空格的文本，因為空格符是用于分隔各參數的，所以不能包含空格。同 -d 類似，假如指定了 -windowtitle 選項，則必須指定標題文本。
　　到此為止，Java 文檔和 javadoc 就介紹完了。javadoc 真的能讓我們在 Java 注釋上做文章——生成開發文

上一篇：JavaDoc，在 Java 的注釋上做文章(上)

下一篇：XP 精華:何使 Java 項目獲得更大成功