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

2024-07-21 02:15:15

字體：大中小

來源：轉載

供稿：網友

　　可以通過代碼模板快速的錄入javadoc注釋，你也可以選擇通過javadoc對話框以一種形象化的方式錄入javadoc注釋。此外，jbuilder還提供了各種javadoc的輔助功能，如javadocinsight誘導錄入，沖突報告和更正，特殊的todo標簽等。

　　1、javadoc對話框

　　在編輯器中，將光標放在類、方法、值域等元素定義處右擊，在彈出的菜單中選擇add->javadoc for xxx將調出javadoc對話框。
打開person.java文件，將光標移到構造函數中，依照上述操作步驟調出javadoc對話框，如下圖所示：

圖 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在編輯器中生成這個新的標簽。

圖 10 add javadoc tag對話框

　　實戰經驗：

　　雖然使用javadoc對話框可以以一種形象的方式創建javadoc注釋，減少沖突概率，但由于需要在多個彈出的對話框中操作，且需要使用到鍵盤和鼠標，所以在鍵入速度和操作連貫性都很差。筆者在開發過程中幾乎從未使用這種笨重的方法，既然是己所不欲，當然也不希望讀者朋友使用。但初學者卻可以通過javadoc對話框加強對javadoc標簽的理解。

　　2、使用javadocinsight

　　象memberinsight、parameterinsight等一樣，javadocinsight以誘導的方式輔助你快速錄入正確的javadoc標簽。

　　由于javadoc標簽都帶有@字符，當你錄入@字符后javadocinsight誘導窗口自動彈出，延時時間可以通過tools->perferences...->editor->codeinsight設置頁中調整，默認為250ms。一個典型的javadocinsight窗口如下圖所示：

圖 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出現在列表中，如下圖所示：

圖 12 javadoc自定義標簽設置頁

　　2．按new...按鈕，彈出create custom tag對話框，如下圖所示：

圖 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文檔如下圖所示的文檔：

圖 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對話框，如下圖所示：

圖 15 創建新代碼模板對話框

　　·template name：clscmt 模板的名字

　　·description：class’s comment 模板描述信息

　　2) 在code中錄入代碼清單 2的代碼，其中帶$前綴的標識是一個宏操作符，在調整模板錄入注釋塊后，宏將被替換成具體的值，你可以通過macro...按鈕，在insert macro對話框中選擇一個宏，如下圖所示：

圖 16 插入宏對話框

　　3) 錄入代碼模板后，按ok返回common設置頁，再按ok后完成創建clscmt代碼模板。

　　創建完clscmt模板后，你就可以在編輯器中用ctrl+j調用這個模板了，如下圖所示：

圖 17 調用clscmt代碼模板

　　錄入clscmt代碼模板后，將產生一個類注釋塊，原$author和$version宏已經被替換成project->project properties...->general設置頁的class javadoc fields列表中所設置的值了，如下圖所示：

圖 18 用代碼模板錄入javadoc注釋塊

　　此時，general設置頁的class javadoc fields列表的設置情況如下圖所示：

圖 19 javadoc域設置

　　5、javadoc注釋沖突

　　javadoc注釋是對源碼程序的說明，所以注釋必須和源程序保持一致。假設一個方法共有兩個入參，但對應的javadoc僅對其中一個入參用@param進行了說明，兩者出現了不一致，這時就出現了注釋沖突。jbuilder能夠檢查出這種不一致的沖突，結構窗格樹中將出現一個javadoc conflicts的文件夾，報告當前java文件中所有的注釋沖突，如下圖所示：

圖 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文件夾下，如下圖所示：

圖 21 to do文件夾

　　點擊to do文件夾下的項目，編輯器定位到代碼中相應的位置。

　　如果你在工程的許多地方都插入了todo標簽，如何查看檢索查看它們呢？通過search->view todos，信息窗格中將列出工程中所有的todo標記，如下圖所示：

圖 22 工程或工程組中所有todo標記

　　不但包含了todo的注釋信息，結果列表中還列出了標記所在的程序文件及目錄。你可以在comment contains中輸入關鍵字對todo標記的注釋進行查詢過濾。

　　提示：

　　一個工程性的軟件項目，往往由于項目進度的緊迫，囿于時間和人力資源，你可能不得不舍棄一些好的解決方法而用一些易于實現的方法應急。你希望將來在允許的條件下再"重拾舊山河"，常言道，好記性不如爛筆頭，如果在相應的地方用todo標簽象武陵人從桃花源返回一樣"處處志之"，就不會"遂迷不復得"了。

上一篇：JBuilder開發常用的十九個快捷鍵

下一篇：JBuilder2005創建開發文檔之標簽介紹