JBuilder2005創建開發文檔之編寫注釋

2019-11-18 12:01:08

字體：大中小

來源：轉載

供稿：網友

　　可以通過代碼模板快速的錄入javadoc注釋，你也可以選擇通過Javadoc對話框以一種形象化的方式錄入Javadoc注釋。此外，JBuilder還提供了各種Javadoc的輔助功能，如JavadocInsight誘導錄入，沖突報告和更正，非凡的todo標簽等。
　　
　　1、Javadoc對話框
　　
　　在編輯器中，將光標放在類、方法、值域等元素定義處右擊，在彈出的菜單中選擇Add->Javadoc for XXX將調出Javadoc對話框。
　　打開Person.java文件，將光標移到構造函數中，依照上述操作步驟調出Javadoc對話框，如下圖所示：
　　　 JBuilder2005創建開發文檔之編寫注釋（圖一）

　　圖 9 Javadoc對話框
　　
　　在Description中列出了構造函數的描述信息，而Tags中列出構造函數所有Javadoc注釋標簽。你可以通過對話框右下角的按鈕新增、編輯、刪除標簽，也可以調整它們的位置。
　　
　　下面，我們為構造函數添加一個新的@see標簽，鏈接到Car.drive(int direction,int speed)函數中。
　　
　　1．點擊Javadoc for ConstrUCtor "Person"對話框的Add...按鈕，彈出Add Javadoc Tag對話框，如圖 10所示。
　　
　　2．從Tag下拉框中選擇see選項。
　　
　　3．在Description中錄入javadoc.tool.Car#drive(int,int)。
　　
　　4．按OK返回Javadoc for Constructor "Person"對話框，再按OK在編輯器中生成這個新的標簽。
　　　 JBuilder2005創建開發文檔之編寫注釋（圖二）

　　圖 10 Add Javadoc Tag對話框
　　
　　實戰經驗：
　　
　　雖然使用Javadoc對話框可以以一種形象的方式創建Javadoc注釋，減少沖突概率，但由于需要在多個彈出的對話框中操作，且需要使用到鍵盤和鼠標，所以在鍵入速度和操作連貫性都很差。筆者在開發過程中幾乎從未使用這種粗笨的方法，既然是己所不欲，當然也不希望讀者朋友使用。但初學者卻可以通過Javadoc對話框加強對Javadoc標簽的理解。
　　
　　2、使用JavadocInsight
　　
　　象MemberInsight、ParameterInsight等一樣，JavadocInsight以誘導的方式輔助你快速錄入正確的Javadoc標簽。
　　
　　由于Javadoc標簽都帶有@字符，當你錄入@字符后JavadocInsight誘導窗口自動彈出，延時時間可以通過Tools->Perferences...->Editor->CodeInsight設置頁中調整，默認為250ms。一個典型的JavadocInsight窗口如下圖所示：
　　　 JBuilder2005創建開發文檔之編寫注釋（圖三）

　　圖 11 JavadocInsight
　　
　　在注釋塊中除可以用JavadocInsight誘導窗口外，可以通過Ctrl+Space使用MemberInsight誘導窗口錄入類值域或方法，通過Ctrl+Alt+Space使用ClassInsight錄入類名。JavadocInsight、MemberInsight和ClassInsight有如三劍客，保證快速和正確地錄入Javadoc注釋段。
　　
　　提示：
　　
　　JavadocInsight窗口中除todo外都顯示為粗體樣式，todo標簽不是Javadoc標準的標簽，而是JBuilder自定義的標簽。JBuilder答應定義自定義的Javadoc標簽，所有自定義的Javadoc標簽顯示為非粗體樣式。關于自定義Javadoc標簽及todo標簽的具體內容，參見本文后續的內容。
　　
　　3、自定義的Javadoc標簽
　　
　　JBuilder答應你為了實現非凡的用途自定義擴展的Javadoc標簽。在這小節里，我們來定義一個名為notice的自定義標簽。
　　
　　1．Project->Project Properties...->Build->Javadoc，在Javadoc設置頁中列出了所有自定義的Javadoc標簽。由于todo標簽是JBuilder本身自定義標簽，所以todo出現在列表中，如下圖所示：
　　　 JBuilder2005創建開發文檔之編寫注釋（圖四）

　　圖 12 Javadoc自定義標簽設置頁
　　
　　2．按New...按鈕，彈出Create Custom Tag對話框，如下圖所示：
　　　 JBuilder2005創建開發文檔之編寫注釋（圖五）

　　圖 13 創建自定義Javadoc標簽對話框
　　
　　·Tag name：notice，標簽名
　　
　　·Heading Text：出現在Javadoc 文檔中的標題。
　　
　　·Placement options：選擇所有的選項，表示這個標簽可以對代碼中的任何類型元素進行注釋。
　　
　　3．按OK創建這個notice自定義標簽。
　　
　　打開Person.java用notice標簽為sex值域寫Javadoc注釋：
　　
　　1) /**@notice 這是用于表示性別的變量，合法值只能為MALE和FEMALE*/
　　2) PRotected int sex;
　　
　　對應的Javadoc文檔如下圖所示的文檔：
　　　 JBuilder2005創建開發文檔之編寫注釋（圖六）

　　圖 14 自定義Javadoc標簽生成的文檔
　　
　　其中"注重"為Create Custom Tag對話框中的Heading text的內容，在上圖中我們特地標識出來。
　　
　　4、使用代碼模板
　　
　　在第4章中我們曾經介紹過代碼模板，你同樣可以為常用的注釋塊創建一個Javadoc模板，"多快好省"地錄入Javadoc注釋。
　　按照習慣方式，每個類都需要一個類注釋，類注釋都是相似的，下面我們就來創建一個類注釋代碼模板，這個代碼模板如下所示：
　　
　　代碼清單 2 類注釋代碼模板
　　
　　1. /**
　　2. * <pre></pre>
　　3. * @see
　　4. * @version $Version, 2005-04-
　　5. * @author $Author
　　6. * @since JDK1.3
　　7. */
　　
　　1) Tools->Perferences...->Editor->Templates->Common，點擊Common設置頁的Add...按鈕，彈出New Code Template對話框，如下圖所示：
　　　 JBuilder2005創建開發文檔之編寫注釋（圖七）

　　圖 15 創建新代碼模板對話框
　　
　　·Template name：clscmt 模板的名字
　　
　　·Description：class’s comment 模板描述信息
　　
　　2) 在Code中錄入代碼清單 2的代碼，其中帶$前綴的標識是一個宏操作符，在調整模板錄入注釋塊后，宏將被替換成具體的值，你可以通過Macro...按鈕，在Insert Macro對話框中選擇一個宏，如下圖所示：
　　　 JBuilder2005創建開發文檔之編寫注釋（圖八）

　　圖 16 插入宏對話框
　　
　　3) 錄入代碼模板后，按OK返回Common設置頁，再按OK后完成創建clscmt代碼模板。
　　
　　創建完clscmt模板后，你就可以在編輯器中用Ctrl+J調用這個模板了，如下圖所示：
　　　 JBuilder2005創建開發文檔之編寫注釋（圖九）

　　圖 17 調用clscmt代碼模板
　　
　　錄入clscmt代碼模板后，將產生一個類注釋塊，原$Author和$Version宏已經被替換成Project->Project Properties...->General設置頁的class Javadoc fields列表中所設置的值了，如下圖所示：
　　　 JBuilder2005創建開發文檔之編寫注釋（圖十）

　　圖 18 用代碼模板錄入Javadoc注釋塊
　　
　　此時，General設置頁的class Javadoc fields列表的設置情況如下圖所示：
　　　 JBuilder2005創建開發文檔之編寫注釋（圖十）

　　圖 19 Javadoc域設置
　　
　　5、Javadoc注釋沖突
　　
　　Javadoc注釋是對源碼程序的說明，所以注釋必須和源程序保持一致。假設一個方法共有兩個入參，但對應的Javadoc僅對其中一個入參用@param進行了說明，兩者出現了不一致，這時就出現了注釋沖突。JBuilder能夠檢查出這種不一致的沖突，結構窗格樹中將出現一個Javadoc Conflicts的文件夾，報告當前Java文件中所有的注釋沖突，如下圖所示：
　　　 JBuilder2005創建開發文檔之編寫注釋（圖十二）

　　圖 20 Javadoc沖突報告
　　
　　每條沖突注釋不但給出了沖突原因的簡要描述，還指定了沖突發生的位置。你可以點擊某沖突項，在彈出的對話框中選擇Fix Javadoc Conflict for "XXX"修復這個沖突。你也可以右擊Javadoc Conflicts文件夾，在彈出的菜單中選擇Fix Javadoc Conflicts修復全部的沖突。
　　
　　注重：
　　
　　Javadoc沖突只有在Errors文件夾中所有的語法錯誤都已經得到解決后才會報告出來。
　　
　　6、todo標簽
　　
　　todo是JBuilder自定義的標簽，但它并不用于生成Javadoc文檔的內容。它相當于一個"助記符"，表示此處有一個未完成的工作或一個待改進的工作，方便日后檢索和處理這些未盡之事。
　　
　　當前程序文件中的所有todo標簽歸結在結構窗格的To Do文件夾下。假設我們在Person.java中添加兩個todo標簽，如下所示：
　　
　　1. …
　　2. public class Person implements Serializable
　　3. {
　　4. 　public Person(String name ,int sex) throws PersonArgumentException
　　5. 　{
　　6. 　　if(sex != MALE && sex != FEMALE)
　　7. 　　　throw new PersonArgumentException("參數不正確");
　　8. 　　　/** @todo 還需做更多的校驗 */
　　9. 　　　this.name = name;
　　10.　　　this.sex = sex;
　　11.　}
　　12.　 …
　　13.　 /**
　　14.　 * 設置性別
　　15.　 * @param sex int
　　16.　 */
　　17.　 public void setSex(int sex)
　　18.　 {
　　19. 　　/** @todo 需要對入參做判定 */
　　20. 　　this.sex = sex;
　　21. 　}
　　22. }
　　
　　在第8、19行添加上兩個todo標簽。todo標簽可以放在程序的任何地方，而不象Javadoc標簽一樣必須放置在類、接口、方法等定義語句的前面。此時，這兩個todo標簽都將出現在結構窗格的To Do文件夾下，如下圖所示：
　　　 JBuilder2005創建開發文檔之編寫注釋（圖十三）