JBuilder2005創建開發文檔之編寫注釋
可以通過代碼模板快速的錄入Javadoc注釋，你也可以選擇通過Javadoc對話框以一種形象化的方式錄入Javadoc注釋。此外，JBuilder還提供了各種Javadoc的輔助功能，如JavadocInsight誘導錄入，沖突報告和更正，特殊的todo標簽等。
1、Javadoc對話框
在編輯器中，將光標放在類、方法、值域等元素定義處右擊，在彈出的菜單中選擇Add->Javadoc for XXX將調出Javadoc對話框。
打開Person.java文件，將光標移到構造函數中，依照上述操作步驟調出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在編輯器中生成這個新的標簽。
實戰經驗：
雖然使用Javadoc對話框可以以一種形象的方式創建Javadoc注釋，減少沖突概率，但由于需要在多個彈出的對話框中操作，且需要使用到鍵盤和鼠標，所以在鍵入速度和操作連貫性都很差。筆者在開發過程中幾乎從未使用這種笨重的方法，既然是己所不欲，當然也不希望讀者朋友使用。但初學者卻可以通過Javadoc對話框加強對Javadoc標簽的理解。
2、使用JavadocInsight
象MemberInsight、ParameterInsight等一樣，JavadocInsight以誘導的方式輔助你快速錄入正確的Javadoc標簽。
由于Javadoc標簽都帶有@字符，當你錄入@字符后JavadocInsight誘導窗口自動彈出，延時時間可以通過Tools->Perferences...->Editor->CodeInsight設置頁中調整，默認為250ms。一個典型的JavadocInsight窗口如下圖所示：
在注釋塊中除可以用JavadocInsight誘導窗口外，可以通過Ctrl+Space使用MemberInsight誘導窗口錄入類值域或方法，通過Ctrl+Alt+Space使用ClassInsight錄入類名。JavadocInsight、MemberInsight和ClassInsight有如三劍客，保證快速和正確地錄入Javadoc注釋段。
3、自定義的Javadoc標簽
JBuilder允許你為了實現特殊的用途自定義擴展的Javadoc標簽。在這小節里，我們來定義一個名為notice的自定義標簽。
1．Project->Project Properties...->Build->Javadoc，在Javadoc設置頁中列出了所有自定義的Javadoc標簽。由于todo標簽是JBuilder本身自定義標簽，所以todo出現在列表中，如下圖所示：
2．按New...按鈕，彈出Create Custom Tag對話框，如下圖所示：
·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文檔如下圖所示的文檔：
其中"注意"為Create Custom Tag對話框中的Heading text的內容，在上圖中我們特地標識出來。
4、使用代碼模板
在第4章中我們曾經介紹過代碼模板，你同樣可以為常用的注釋塊創建一個Javadoc模板，"多快好省"地錄入Javadoc注釋。
按照習慣方式，每個類都需要一個類注釋，類注釋都是相似的，下面我們就來創建一個類注釋代碼模板，這個代碼模板如下所示：
代碼清單 2 類注釋代碼模板
1) Tools->Perferences...->Editor->Templates->Common，點擊Common設置頁的Add...按鈕，彈出New Code Template對話框，如下圖所示：
·Template name：clscmt 模板的名字
·Description：class’s comment 模板描述信息
2) 在Code中錄入代碼清單 2的代碼，其中帶$前綴的標識是一個宏操作符，在調整模板錄入注釋塊后，宏將被替換成具體的值，你可以通過Macro...按鈕，在Insert Macro對話框中選擇一個宏，如下圖所示：
3) 錄入代碼模板后，按OK返回Common設置頁，再按OK后完成創建clscmt代碼模板。
創建完clscmt模板后，你就可以在編輯器中用Ctrl+J調用這個模板了，如下圖所示：
錄入clscmt代碼模板后，將產生一個類注釋塊，原$Author和$Version宏已經被替換成Project->Project Properties...->General設置頁的class Javadoc fields列表中所設置的值了，如下圖所示：
此時，General設置頁的class Javadoc fields列表的設置情況如下圖所示：
5、Javadoc注釋沖突
Javadoc注釋是對源碼程序的說明，所以注釋必須和源程序保持一致。假設一個方法共有兩個入參，但對應的Javadoc僅對其中一個入參用@param進行了說明，兩者出現了不一致，這時就出現了注釋沖突。JBuilder能夠檢查出這種不一致的沖突，結構窗格樹中將出現一個Javadoc Conflicts的文件夾，報告當前Java文件中所有的注釋沖突，如下圖所示：
每條沖突注釋不但給出了沖突原因的簡要描述，還指定了沖突發生的位置。你可以點擊某沖突項，在彈出的對話框中選擇Fix Javadoc Conflict for "XXX"修復這個沖突。你也可以右擊Javadoc Conflicts文件夾，在彈出的菜單中選擇Fix Javadoc Conflicts修復全部的沖突。
注意：
Javadoc沖突只有在Errors文件夾中所有的語法錯誤都已經得到解決后才會報告出來。
6、todo標簽
todo是JBuilder自定義的標簽，但它并不用于生成Javadoc文檔的內容。它相當于一個"助記符"，表示此處有一個未完成的工作或一個待改進的工作，方便日后檢索和處理這些未盡之事。
當前程序文件中的所有todo標簽歸結在結構窗格的To Do文件夾下。假設我們在Person.java中添加兩個todo標簽，如下所示：
在第8、19行添加上兩個todo標簽。todo標簽可以放在程序的任何地方，而不象Javadoc標簽一樣必須放置在類、接口、方法等定義語句的前面。此時，這兩個todo標簽都將出現在結構窗格的To Do文件夾下，如下圖所示：
點擊To Do文件夾下的項目，編輯器定位到代碼中相應的位置。
如果你在工程的許多地方都插入了todo標簽，如何查看檢索查看它們呢？通過Search->View Todos，信息窗格中將列出工程中所有的todo標記，如下圖所示：
不但包含了todo的注釋信息，結果列表中還列出了標記所在的程序文件及目錄。你可以在Comment contains中輸入關鍵字對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標簽象武陵人從桃花源返回一樣"處處志之"，就不會"遂迷不復得"了。 |