原標(biāo)題：java注釋文檔(下)

3. 使用 @param、@return 和 @exception 說明方法

這三個標(biāo)記都是只用于方法的。@param 描述方法的參數(shù)，@return 描述方法的返回值，@exception 描述方法可能拋出的異常。它們的句法如下：

@param 參數(shù)名 參數(shù)說明@return 返回值說明@exception 異常類名說明

每一個 @param 只能描述方法的一個參數(shù)，所以，如果方法需要多個參數(shù)，就需要多次使用 @param 來描述。

一個方法中只能用一個 @return，如果文檔說明中列了多個 @return，則 javadoc 編譯時會發(fā)出警告，且只有第一個 @return 在生成的文檔中有效。

方法可能拋出的異常應(yīng)當(dāng)用 @exception 描述。由于一個方法可能拋出多個異常，所以可以有多個 @exception。每個 @exception 后面應(yīng)有簡述的異常類名，說明中應(yīng)指出拋出異常的原因。需要注意的是，異常類名應(yīng)該根據(jù)源文件的 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 編譯生成的文檔相關(guān)部分如下圖：

可以看到，上例中 @param b excrescent parameter 一句是多余的，因為參數(shù)只是一個 n，并沒有一個 b 但是 javadoc 編譯時并沒有檢查。因此，寫文檔注釋時一定要正確匹配參數(shù)表與方法中正式參數(shù)表的項目。如果方法參數(shù)表中的參數(shù)是 a，文檔中卻給出對參數(shù) x 的解釋，或者再多出一個參數(shù) i，就會讓人摸不著頭腦了。@exceptin 也是一樣。

上例程序中并沒有拋出一個 NullPointerException，但是文檔注釋中為什么要寫上這么一句呢，難道又是為了演示？這不是為了演示描述多余的異常也能通過編譯，而是為了說明寫異常說明時應(yīng)考運行時 (RunTime) 異常的可能性。上例程序中，如果參數(shù) n 是給的一個空值 (null)，那么程序會在運行的時候拋出一個 NullPointerException，因此，在文檔注釋中添加了對 NullPointerException 的說明。

上例中的 @return 語句有兩個，但是根據(jù)規(guī)則，同一個方法中，只有第一個 @return 有效，其余的會被 javadoc 忽略。所以生成的文檔中沒有出現(xiàn)第二個 @return 的描述。

講到這里，該怎么寫文檔注釋你應(yīng)該已經(jīng)清楚了，下面就開始講解 javadoc 的常用命令。

四、 javadoc命令

運行 javadoc -help 可以看到 javadoc 的用法，這里列舉常用參數(shù)如下：

用法：javadoc [options] [packagenames] [sourcefiles]

選項：

javadoc 編譯文檔時可以給定包列表，也可以給出源程序文件列表。例如在 CLASSPATH 下有兩個包若干類如下：

fancy.Editorfancy.Testfancy.editor.ECommandfancy.editor.EDocumentfancy.editor.EView

這里有兩個包 (fancy 和 fancy.editor) 和5個類。那么編譯時 (Windows 環(huán)境) 可以使用如下 javadoc 命令：

javadoc fancy\Test.java fancy\Editor.java fancy\editor\ECommand.java fancy\editor\EDocument.java fancy\editor\EView.java

這是給出 java 源文件作為編譯參數(shù)的方法，注意命令中指出的是文件路徑，應(yīng)該根據(jù)實際情況改變。也可以是給出包名作為編譯參數(shù)，如：

javadoc fancy fancy.editor

用瀏覽器打開生成文檔的 index.html 文件即可發(fā)現(xiàn)兩種方式編譯結(jié)果的不同，如下圖：

用第二條命令生成的文檔被框架分成了三部分：包列表、類列表和類說明。在包列表中選擇了某個包之后，類列表中就會列出該包中的所有類；在類列表中選擇了某個類之后，類說明部分就會顯示出該類的詳細(xì)文檔。而用第一條命令生成的文檔只有兩部分，類列表和類說明，沒有包列表。這就是兩種方式生成文檔的最大區(qū)別了。

下面再來細(xì)說選項。-public、-protected、-package、-private 四個選項，只需要任選其一即可。它們指定的顯示類成員的程度。它們顯示的成員多少是一個包含的關(guān)系，如下表：

-d 選項允許你定義輸出目錄。如果不用 -d 定義輸出目錄，生成的文檔文件會放在當(dāng)前目錄下。-d 選項的用法是

-d目錄名

目錄名為必填項，也就是說，如果你使用了 -d 參數(shù)，就一定要為它指定一個目錄。這個目錄必須已經(jīng)存在了，如果還不存在，請在運行 javadoc 之前創(chuàng)建該目錄。

-version 和 -author 用于控制生成文檔時是否生成 @version 和 @author 指定的內(nèi)容。不加這兩個參數(shù)的情況下，生成的文檔中不包含版本和作者信息。

-splitindex 選項將索引分為每個字母對應(yīng)一個文件。默認(rèn)情況下，索引文件只有一個，且該文件中包含所有索引內(nèi)容。當(dāng)然生成文檔內(nèi)容不多的時候，這樣做非常合適，但是， 如果文檔內(nèi)容非常多的時候，這個索引文件將包含非常多的內(nèi)容，顯得過于龐大。使用 -splitindex 會把索引文件按各索引項的第一個字母進(jìn)行分類，每個字母對應(yīng)一個文件。這樣，就減輕了一個索引文件的負(fù)擔(dān)。

-windowtitle 選項為文檔指定一個標(biāo)題，該標(biāo)題會顯示在窗口的標(biāo)題欄上。如果不指定該標(biāo)題，而默認(rèn)的文檔標(biāo)題為“生成的文檔(無標(biāo)題)”。該選項的用法是：

-windowtitle 標(biāo)題

標(biāo)題是一串沒有包含空格的文本，因為空格符是用于分隔各參數(shù)的，所以不能包含空格。同 -d 類似，如果指定了 -windowtitle 選項，則必須指定標(biāo)題文本。

到此為止，Java 文檔和 javadoc 就介紹完了。javadoc 真的能讓我們在 Java 注釋上做文章——生成開發(fā)文檔。

轉(zhuǎn)發(fā)分享是一種美德返回搜狐，查看更多

責(zé)任編輯：

《新程序員》：云原生和全面數(shù)字化實踐50位技術(shù)專家共同創(chuàng)作，文字、視頻、音頻交互閱讀

總結(jié)

以上是生活随笔為你收集整理的java注释 param_java注释文档（下）的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。