在IntelliJ IDEA中為自己設計的類庫生成JavaDoc的方法示例
因為某個專案需要,為團隊其他兄弟姐妹開發了一個 XML 分析處理器,並將其設計為一個類庫,提供相應的 API 介面。為了方便大家的使用,需要生成對應的 JavaDoc 幫助文件,就像 JavaSE 標準庫提供的 JavaDoc 那樣。我的開發工具為 IntelliJ IDEA 12.1.6,本身提供了很好的 JavaDoc 生成功能,以及標準 JavaDoc 註釋轉換功能,其實質是在程式碼編寫過程中,按照標準 JavaDoc 的註釋要求,為需要暴露給使用者的類、方法以及其他成員編寫註釋。然後使用 IDEA 的功能自動呼叫 javadoc.exe(JDK 自帶的工具)根據原始碼中的註釋內容自動生成 JavaDoc 文件(超文字格式)。標準 JavaDoc 的註釋規則,大家可以在網上很容易搜尋到,這裡有幾點倒是要特別注意一下:
1.IDEA 的 JavaDoc 生成功能在選單 Tools->Generate JavaDoc 項裡面。
2.點選上述選單項後,會出現生成 JavaDoc 的對話方塊,一般的選項都很直觀,不必細說。但是要注意生成 JavaDoc 的原始碼物件的選擇,一般以模組(Module)為主,必要時可以單獨選擇必要的 Java 原始碼檔案,不推薦以 Project 為 JavaDoc 生成的源範圍。
3.裡面有一個 Locale 可選填項,表示的是需要生成的 JavaDoc 以何種語言版本展示,根據 javadoc.exe 的幫助說明,這其實對應的就是 javadoc.exe 的 -locale 引數,如果不填,預設可能是英文或者是當前作業系統的語言,既然是國人,建議在此填寫 zh_CN,這樣生成的 JavaDoc 就是中文版本的,當然指的是 JavaDoc 的框架中各種通用的固定顯示區域都是中文的。你自己編寫的註釋轉換的內容還是根據你註釋的內容來。
4.還有一個“Other command line arguments:”可選填項,非常重要,是填寫直接向 javadoc.exe 傳遞的引數內容。因為有一些重要的設定,只能通過直接引數形式向 javadoc.exe 傳遞。這裡必須要填寫如下引數:
-encoding UTF-8 -charset UTF-8 -windowtitle "你的文件在瀏覽器視窗標題欄顯示的內容" -link http://docs.oracle.com/javase/7/docs/api
5.第一個引數 -encoding UTF-8 表示你的原始碼(含有符合 JavaDoc 標準的註釋)是基於 UTF-8 編碼的,以免處理過程中出現中文等非英語字元亂碼;第二個引數 -charset UTF-8 表示在處理並生成 JavaDoc 超文字時使用的字符集也是以 UTF-8 為編碼,目前所有瀏覽器都支援 UTF-8,這樣最具有通用性,支援中文非常好;第三個引數 -windowtitle 表示生成的 JavaDoc 超文字在瀏覽器中開啟時,瀏覽器視窗標題欄顯示的文字內容;第四個引數 -link 很重要,它表示你生成的 JavaDoc 中涉及到很多對其他外部 Java 類的引用,是使用全限定名稱還是帶有超連結的短名稱,舉個例子,我建立了一個方法 public void func(String arg),這個方法在生成 JavaDoc 時如果不指定 -link 引數,則 JavaDoc 中對該方法的表述就會自動變為 public void func(java.lang.String arg),因為 String 這個類對我自己實現的類來講就是外部引用的類,雖然它是 Java 標準庫的類。如果指定了 -link http://docs.oracle.com/javase/7/docs/api 引數,則 javadoc.exe 在生成 JavaDoc 時,會使用 String 這樣的短名稱而非全限定名稱 java.lang.String,同時自動為 String 短名稱生成一個超連結,指向官方 JavaSE 標準文件 http://docs.oracle.com/javase/7/docs/api 中對 String 類的詳細文件地址。-link 實質上是告訴 javadoc.exe 根據提供的外部引用類的 JavaDoc 地址去找一個叫 package-list 的文字檔案,在這個文字檔案中包含了所有外部引用類的全限定名稱,因此生成的新 JavaDoc 不必使用外部引用類的全限定名,只需要使用短名稱,同時可以自動建立指向其外部引用 JavaDoc 中的詳細文件超連結。每個 JavaDoc 都會在根目錄下有一個 package-list 檔案,包括我們自己生成的 JavaDoc。
JavaDoc 生成完畢,即可在其根目錄下找到 index.html 檔案,開啟它就可以看到我們自己的標準 JavaDoc API 文件啦。
javadoc常用標識
@author 作者
@version 版本號
@param 引數名 描述 方法的入參名及描述資訊,如入參有特別要求,可在此註釋。
@return 描述 對函式返回值的註釋
@deprecated 過期文字 標識隨著程式版本的提升,當前API已經過期,僅為了保證相容性依然存在,以此告之開發者不應再用這個API。
@throws異常類名 建構函式或方法所會丟擲的異常。
@exception 異常類名 同@throws。
@see 引用 檢視相關內容,如類、方法、變數等。
@since 描述文字 API在什麼程式的什麼版本後開發支援。
{@link包.類#成員 標籤} 連結到某個特定的成員對應的文件中。
{@value} 當對常量進行註釋時,如果想將其值包含在文件中,則通過該標籤來引用常量的值。
到此這篇關於在IntelliJ IDEA中為自己設計的類庫生成JavaDoc的方法示例的文章就介紹到這了,更多相關IDEA生成JavaDoc內容請搜尋我們以前的文章或繼續瀏覽下面的相關文章希望大家以後多多支援我們!