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

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

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

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

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

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

方法可能拋出的異常應(yīng)當(dāng)用 @exception 描述。由于一個(gè)方法可能拋出多個(gè)異常，所以可以有多個(gè) @exception。每個(gè) @exception 后面應(yīng)有簡(jiǎn)述的異常類名，說明中應(yīng)指出拋出異常的原因。需要注意的是，異常類名應(yīng)該根據(jù)源文件的 import 語(yǔ)句確定是寫出類名還是類全名。示例如下：

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 一句是多余的，因?yàn)閰?shù)只是一個(gè) n，并沒有一個(gè) b 但是 javadoc 編譯時(shí)并沒有檢查。因此，寫文檔注釋時(shí)一定要正確匹配參數(shù)表與方法中正式參數(shù)表的項(xiàng)目。如果方法參數(shù)表中的參數(shù)是 a，文檔中卻給出對(duì)參數(shù) x 的解釋，或者再多出一個(gè)參數(shù) i，就會(huì)讓人摸不著頭腦了。@exceptin 也是一樣。

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

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

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

四、 javadoc命令

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

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

選項(xiàng)：

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

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

這里有兩個(gè)包 (fancy 和 fancy.editor) 和5個(gè)類。那么編譯時(shí) (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í)際情況改變。也可以是給出包名作為編譯參數(shù)，如：

javadoc fancy fancy.editor

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

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

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

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

-d目錄名

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

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

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

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

-windowtitle 標(biāo)題

標(biāo)題是一串沒有包含空格的文本，因?yàn)榭崭穹怯糜诜指舾鲄?shù)的，所以不能包含空格。同 -d 類似，如果指定了 -windowtitle 選項(xiàng)，則必須指定標(biāo)題文本。

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

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

責(zé)任編輯：

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

總結(jié)

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

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