JBuilder2005創(chuàng)建開發(fā)文檔之編寫注釋

2019-11-18 12:01:08

字體：大中小

供稿：網(wǎng)友

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

　　圖 9 Javadoc對話框
　　
　　在Description中列出了構(gòu)造函數(shù)的描述信息，而Tags中列出構(gòu)造函數(shù)所有Javadoc注釋標(biāo)簽。你可以通過對話框右下角的按鈕新增、編輯、刪除標(biāo)簽，也可以調(diào)整它們的位置。
　　
　　下面，我們?yōu)闃?gòu)造函數(shù)添加一個新的@see標(biāo)簽，鏈接到Car.drive(int direction,int speed)函數(shù)中。
　　
　　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在編輯器中生成這個新的標(biāo)簽。
　　　 JBuilder2005創(chuàng)建開發(fā)文檔之編寫注釋（圖二）

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

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

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

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

　　圖 14 自定義Javadoc標(biāo)簽生成的文檔
　　
　　其中"注重"為Create Custom Tag對話框中的Heading text的內(nèi)容，在上圖中我們特地標(biāo)識出來。
　　
　　4、使用代碼模板
　　
　　在第4章中我們曾經(jīng)介紹過代碼模板，你同樣可以為常用的注釋塊創(chuàng)建一個Javadoc模板，"多快好省"地錄入Javadoc注釋。
　　按照習(xí)慣方式，每個類都需要一個類注釋，類注釋都是相似的，下面我們就來創(chuàng)建一個類注釋代碼模板，這個代碼模板如下所示：
　　
　　代碼清單 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設(shè)置頁的Add...按鈕，彈出New Code Template對話框，如下圖所示：
　　　 JBuilder2005創(chuàng)建開發(fā)文檔之編寫注釋（圖七）

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

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

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

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

　　圖 19 Javadoc域設(shè)置
　　
　　5、Javadoc注釋沖突
　　
　　Javadoc注釋是對源碼程序的說明，所以注釋必須和源程序保持一致。假設(shè)一個方法共有兩個入?yún)?，但對?yīng)的Javadoc僅對其中一個入?yún)⒂聾param進(jìn)行了說明，兩者出現(xiàn)了不一致，這時就出現(xiàn)了注釋沖突。JBuilder能夠檢查出這種不一致的沖突，結(jié)構(gòu)窗格樹中將出現(xiàn)一個Javadoc Conflicts的文件夾，報告當(dāng)前Java文件中所有的注釋沖突，如下圖所示：
　　　 JBuilder2005創(chuàng)建開發(fā)文檔之編寫注釋（圖十二）

JBuilder2005創(chuàng)建開發(fā)文檔之編寫注釋（圖十二）

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