在 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 文檔啦。


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM