因?yàn)槟硞€(gè)項(xiàng)目需要，為團(tuán)隊(duì)其他兄弟姐妹開發(fā)了一個(gè) XML 分析處理器，并將其設(shè)計(jì)為一個(gè)類庫，提供相應(yīng)的 API 接口。為了方便大家的使用，需要生成對(duì)應(yīng)的 JavaDoc 幫助文檔，就像 JavaSE 標(biāo)準(zhǔn)庫提供的 JavaDoc 那樣。我的開發(fā)工具為 IntelliJ IDEA 12.1.6，本身提供了很好的 JavaDoc 生成功能，以及標(biāo)準(zhǔn) JavaDoc 注釋轉(zhuǎn)換功能，其實(shí)質(zhì)是在代碼編寫過程中，按照標(biāo)準(zhǔn) JavaDoc 的注釋要求，為需要暴露給使用者的類、方法以及其他成員編寫注釋。然后使用 IDEA 的功能自動(dòng)調(diào)用 javadoc.exe（JDK 自帶的工具）根據(jù)源代碼中的注釋內(nèi)容自動(dòng)生成 JavaDoc 文檔（超文本格式）。標(biāo)準(zhǔn) JavaDoc 的注釋規(guī)則，大家可以在網(wǎng)上很容易搜索到，這里有幾點(diǎn)倒是要特別注意一下：

1.IDEA 的 JavaDoc 生成功能在菜單 Tools->Generate JavaDoc 項(xiàng)里面。

2.點(diǎn)擊上述菜單項(xiàng)后，會(huì)出現(xiàn)生成 JavaDoc 的對(duì)話框，一般的選項(xiàng)都很直觀，不必細(xì)說。但是要注意生成 JavaDoc 的源代碼對(duì)象的選擇，一般以模塊（Module）為主，必要時(shí)可以單獨(dú)選擇必要的 Java 源代碼文件，不推薦以 Project 為 JavaDoc 生成的源范圍。

3.里面有一個(gè) Locale 可選填項(xiàng)，表示的是需要生成的 JavaDoc 以何種語言版本展示，根據(jù) javadoc.exe 的幫助說明，這其實(shí)對(duì)應(yīng)的就是 javadoc.exe 的 -locale 參數(shù)，如果不填，默認(rèn)可能是英文或者是當(dāng)前操作系統(tǒng)的語言，既然是國人，建議在此填寫 zh_CN，這樣生成的 JavaDoc 就是中文版本的，當(dāng)然指的是 JavaDoc 的框架中各種通用的固定顯示區(qū)域都是中文的。你自己編寫的注釋轉(zhuǎn)換的內(nèi)容還是根據(jù)你注釋的內(nèi)容來。

4.還有一個(gè)“Other command line arguments:”可選填項(xiàng)，非常重要，是填寫直接向 javadoc.exe 傳遞的參數(shù)內(nèi)容。因?yàn)橛幸恍┲匾脑O(shè)置，只能通過直接參數(shù)形式向 javadoc.exe 傳遞。這里必須要填寫如下參數(shù)：

-encoding UTF-8 -charset UTF-8 -windowtitle "你的文檔在瀏覽器窗口標(biāo)題欄顯示的內(nèi)容" -link http://docs.oracle.com/javase/7/docs/api

5.第一個(gè)參數(shù) -encoding UTF-8 表示你的源代碼（含有符合 JavaDoc 標(biāo)準(zhǔn)的注釋）是基于 UTF-8 編碼的，以免處理過程中出現(xiàn)中文等非英語字符亂碼；第二個(gè)參數(shù) -charset UTF-8 表示在處理并生成 JavaDoc 超文本時(shí)使用的字符集也是以 UTF-8 為編碼，目前所有瀏覽器都支持 UTF-8，這樣最具有通用性，支持中文非常好；第三個(gè)參數(shù) -windowtitle 表示生成的 JavaDoc 超文本在瀏覽器中打開時(shí)，瀏覽器窗口標(biāo)題欄顯示的文字內(nèi)容；第四個(gè)參數(shù) -link 很重要，它表示你生成的 JavaDoc 中涉及到很多對(duì)其他外部 Java 類的引用，是使用全限定名稱還是帶有超鏈接的短名稱，舉個(gè)例子，我創(chuàng)建了一個(gè)方法 public void func(String arg)，這個(gè)方法在生成 JavaDoc 時(shí)如果不指定 -link 參數(shù)，則 JavaDoc 中對(duì)該方法的表述就會(huì)自動(dòng)變?yōu)?public void func(java.lang.String arg)，因?yàn)?String 這個(gè)類對(duì)我自己實(shí)現(xiàn)的類來講就是外部引用的類，雖然它是 Java 標(biāo)準(zhǔn)庫的類。如果指定了 -link http://docs.oracle.com/javase/7/docs/api 參數(shù)，則 javadoc.exe 在生成 JavaDoc 時(shí)，會(huì)使用 String 這樣的短名稱而非全限定名稱 java.lang.String，同時(shí)自動(dòng)為 String 短名稱生成一個(gè)超鏈接，指向官方 JavaSE 標(biāo)準(zhǔn)文檔 http://docs.oracle.com/javase/7/docs/api 中對(duì) String 類的詳細(xì)文檔地址。-link 實(shí)質(zhì)上是告訴 javadoc.exe 根據(jù)提供的外部引用類的 JavaDoc 地址去找一個(gè)叫 package-list 的文本文件，在這個(gè)文本文件中包含了所有外部引用類的全限定名稱，因此生成的新 JavaDoc 不必使用外部引用類的全限定名，只需要使用短名稱，同時(shí)可以自動(dòng)創(chuàng)建指向其外部引用 JavaDoc 中的詳細(xì)文檔超鏈接。每個(gè) JavaDoc 都會(huì)在根目錄下有一個(gè) package-list 文件，包括我們自己生成的 JavaDoc。

JavaDoc 生成完畢，即可在其根目錄下找到 index.html 文件，打開它就可以看到我們自己的標(biāo)準(zhǔn) JavaDoc API 文檔啦。

javadoc常用標(biāo)識(shí)

@author 作者
@version 版本號(hào)
@param 參數(shù)名 描述 方法的入?yún)⒚懊枋鲂畔?，如入?yún)⒂刑貏e要求，可在此注釋。
@return 描述 對(duì)函數(shù)返回值的注釋
@deprecated 過期文本 標(biāo)識(shí)隨著程序版本的提升，當(dāng)前API已經(jīng)過期，僅為了保證兼容性依然存在，以此告之開發(fā)者不應(yīng)再用這個(gè)API。
@throws異常類名 構(gòu)造函數(shù)或方法所會(huì)拋出的異常。
@exception 異常類名 同@throws。
@see 引用 查看相關(guān)內(nèi)容，如類、方法、變量等。
@since 描述文本 API在什么程序的什么版本后開發(fā)支持。
{@link包.類#成員 標(biāo)簽} 鏈接到某個(gè)特定的成員對(duì)應(yīng)的文檔中。
{@value} 當(dāng)對(duì)常量進(jìn)行注釋時(shí)，如果想將其值包含在文檔中，則通過該標(biāo)簽來引用常量的值。

到此這篇關(guān)于在IntelliJ IDEA中為自己設(shè)計(jì)的類庫生成JavaDoc的方法示例的文章就介紹到這了,更多相關(guān)IDEA生成JavaDoc內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論