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

　　 使用 @author@version 說明類
　　這兩個標記分別用於指明類的作者和版本缺省情況下 javadoc 將其忽略但命令行開關 author 和 version 可以修改這個功能使其包含的信息被輸出這兩個標記的句法如下
　　@author 作者名
　　@version 版本號
　　其中@author 可以多次使用以指明多個作者生成的文檔中每個作者之間使用逗號 () 隔開@version 也可以使用多次只有第一次有效生成的文檔中只會顯示第一次使用 @version 指明的版本號如下例
　　/**
　　* @author Fancy
　　* @author Bird
　　* @version Version
　　* @version Version
　　*/
　　public class TestJavaDoc {
　　}
　　生成文檔的相關部分如圖
　　　
　　從生成文檔的圖示中可以看出兩個 @author 語句都被編譯在文檔中生成了作者列表而兩個 @version 語句中只有第一句被編譯了只生成了一個版本號
　　從圖上看作者列表是以逗號分隔的如果我想分行顯示怎麼辦？另外如果我想顯示兩個以上的版本號又該怎麼辦？
　　——我們可以將上述兩條 @author 語句合為一句把兩個 @version 語句也合為一句
　　@author Fancy＜br＞Bird
　　@version Version ＜br＞Version
　　結果如圖
　　　
　　我們這樣做即達到了目的又沒有破壞規則@author 之後的作者名和 @version 之後的版本號都可以是用戶自己定義的任何 HTML 格式所以我們可以使用 ＜br＞ 標記將其分行顯示同時在一個 @version 中指明兩個用 ＜br＞ 分隔的版本號也沒有破壞只顯示第一個 @version 內容的規則
　　 使用 @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 javalangException throw when switch is
　　* @exception NullPointerException throw when parameter n is null
　　*/
　　public boolean fun(Integer n) throws Exception {
　　switch (nintValue()) {
　　case :
　　break;
　　case :
　　throw new Exception(Test Only);
　　default:
　　return false;
　　}
　　return true;
　　}
　　}
　　使用 javadoc 編譯生成的文檔相關部分如下圖
　　　
　　可以看到上例中 @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 下有兩個包若干類如下
　　fancyEditor
　　fancyTest
　　fancyeditorECommand
　　fancyeditorEDocument
　　fancyeditorEView
　　這裡有兩個包 (fancy 和 fancyeditor) 和 個類那麼編譯時 (Windows 環境) 可以使用如下 javadoc 命令
　　javadoc fancy\Testjava fancy\Editorjava fancy\editor\ECommandjava fancy\editor\EDocumentjava fancy\editor\EViewjava
　　這是給出 java 源文件作為編譯參數的方法注意命令中指出的是文件路徑應該根據實際情況改變也可以是給出包名作為編譯參數如
　　javadoc fancy fancyeditor
　　用浏覽器打開生成文檔的 l 文件即可發現兩種方式編譯結果的不同如下圖
　　
　　用第二條命令生成的文檔被框架分成了三部分包列表類列表和類說明在包列表中選擇了某個包之後類列表中就會列出該包中的所有類在類列表中選擇了某個類之後類說明部分就會顯示出該類的詳細文檔而用第一條命令生成的文檔只有兩部分類列表和類說明沒有包列表這就是兩種方式生成文檔的最大區別了
　　兩種方式編譯還有一點不同
　　下面再來細說選項
　　publicprotectedpackageprivate 四個選項只需要任選其一即可它們指定的顯示類成員的程度它們顯示的成員多少是一個包含的關系如下表
　　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 注釋上做文章——生成開發文
　　
　　
　　
　　
　　
　　
　　
　　
　　
　　

From:http://tw.wingwit.com/Article/program/Java/JSP/201311/19745.html