可以通過代碼模板快速的錄入Javadoc注釋
你也可以選擇通過Javadoc對話框以一種形象化的方式錄入Javadoc注釋
此外
JBuilder還提供了各種Javadoc的輔助功能
如JavadocInsight誘導錄入
沖突報告和更正
特殊的todo標簽等
Javadoc對話框 在編輯器中
將光標放在類
方法
值域等元素定義處右擊
在彈出的菜單中選擇Add
>Javadoc for XXX將調出Javadoc對話框
打開Person
java文件
將光標移到構造函數中
依照上述操作步驟調出Javadoc對話框
如下圖所示
educity
cn/img_
/
/
/
jpg>
圖
Javadoc對話框
在Description中列出了構造函數的描述信息
而Tags中列出構造函數所有Javadoc注釋標簽
你可以通過對話框右下角的按鈕新增
編輯
刪除標簽
也可以調整它們的位置
下面
我們為構造函數添加一個新的@see標簽
鏈接到Car
drive(int direction
int speed)函數中
．點擊Javadoc for Constructor
Person
對話框的Add
按鈕
彈出Add Javadoc Tag對話框
如圖
所示
．從Tag下拉框中選擇see選項
．在Description中錄入javadoc
tool
Car#drive(int
int)
．按OK返回Javadoc for Constructor
Person
對話框
再按OK在編輯器中生成這個新的標簽
educity
cn/img_
/
/
/
jpg>
圖
Add Javadoc Tag對話框
實戰經驗
雖然使用Javadoc對話框可以以一種形象的方式創建Javadoc注釋
減少沖突概率
但由於需要在多個彈出的對話框中操作
且需要使用到鍵盤和鼠標
所以在鍵入速度和操作連貫性都很差
筆者在開發過程中幾乎從未使用這種笨重的方法
既然是己所不欲
當然也不希望讀者朋友使用
但初學者卻可以通過Javadoc對話框加強對Javadoc標簽的理解
使用JavadocInsight 象MemberInsight
ParameterInsight等一樣
JavadocInsight以誘導的方式輔助你快速錄入正確的Javadoc標簽
由於Javadoc標簽都帶有@字符
當你錄入@字符後JavadocInsight誘導窗口自動彈出
延時時間可以通過Tools
>Perferences
>Editor
>CodeInsight設置頁中調整
默認為
ms
一個典型的JavadocInsight窗口如下圖所示
educity
cn/img_
/
/
/
jpg>
圖
JavadocInsight
在注釋塊中除可以用JavadocInsight誘導窗口外
可以通過Ctrl+Space使用MemberInsight誘導窗口錄入類值域或方法
通過Ctrl+Alt+Space使用ClassInsight錄入類名
JavadocInsight
MemberInsight和ClassInsight有如三劍客
保證快速和正確地錄入Javadoc注釋段
提示
JavadocInsight窗口中除todo外都顯示為粗體樣式
todo標簽不是Javadoc標准的標簽
而是JBuilder自定義的標簽
JBuilder允許定義自定義的Javadoc標簽
所有自定義的Javadoc標簽顯示為非粗體樣式
關於自定義Javadoc標簽及todo標簽的詳細內容
參見本文後續的內容
自定義的Javadoc標簽 JBuilder允許你為了實現特殊的用途自定義擴展的Javadoc標簽
在這小節裡
我們來定義一個名為notice的自定義標簽
．Project
>Project Properties
>Build
>Javadoc
在Javadoc設置頁中列出了所有自定義的Javadoc標簽
由於todo標簽是JBuilder本身自定義標簽
所以todo出現在列表中
如下圖所示
educity
cn/img_
/
/
/
jpg>
圖
Javadoc自定義標簽設置頁
．按New
按鈕
彈出Create Custom Tag對話框
如下圖所示
educity
cn/img_
/
/
/
jpg>
圖
創建自定義Javadoc標簽對話框
·Tag name
notice
標簽名
·Heading Text
出現在Javadoc 文檔中的標題
·Placement options
選擇所有的選項
表示這個標簽可以對代碼中的任何類型元素進行注釋
．按OK創建這個notice自定義標簽
打開Person
java用notice標簽為sex值域寫Javadoc注釋
) /**@notice 這是用於表示性別的變量
合法值只能為MALE和FEMALE*/
) protected int sex;
對應的Javadoc文檔如下圖所示的文檔
educity
cn/img_
/
/
/
jpg>
圖
自定義Javadoc標簽生成的文檔
其中
注意
為Create Custom Tag對話框中的Heading text的內容
在上圖中我們特地標識出來
使用代碼模板 在第
章中我們曾經介紹過代碼模板
你同樣可以為常用的注釋塊創建一個Javadoc模板
多快好省
地錄入Javadoc注釋
按照習慣方式
每個類都需要一個類注釋
類注釋都是相似的
下面我們就來創建一個類注釋代碼模板
這個代碼模板如下所示
代碼清單
類注釋代碼模板
/**
* <pre>|</pre>
* @see
* @version $Version
|
* @author $Author
* @since JDK
*/
) Tools
>Perferences
>Editor
>Templates
>Common
點擊Common設置頁的Add
按鈕
彈出New Code Template對話框
如下圖所示
educity
cn/img_
/
/
/
jpg>
圖
創建新代碼模板對話框
·Template name
clscmt 模板的名字
·Description
class
s comment 模板描述信息
) 在Code中錄入代碼清單
的代碼
其中帶$前綴的標識是一個宏操作符
在調整模板錄入注釋塊後
宏將被替換成具體的值
你可以通過Macro
按鈕
在Insert Macro對話框中選擇一個宏
如下圖所示
educity
cn/img_
/
/
/
jpg>
圖
插入宏對話框
) 錄入代碼模板後
按OK返回Common設置頁
再按OK後完成創建clscmt代碼模板
創建完clscmt模板後
你就可以在編輯器中用Ctrl+J調用這個模板了
如下圖所示
educity
cn/img_
/
/
/
jpg>
圖
調用clscmt代碼模板
錄入clscmt代碼模板後
將產生一個類注釋塊
原$Author和$Version宏已經被替換成Project
>Project Properties
>General設置頁的class Javadoc fields列表中所設置的值了
如下圖所示
educity
cn/img_
/
/
/
jpg>
圖
用代碼模板錄入Javadoc注釋塊
此時
General設置頁的class Javadoc fields列表的設置情況如下圖所示
educity
cn/img_
/
/
/
jpg>
圖
Javadoc域設置
Javadoc注釋沖突 Javadoc注釋是對源碼程序的說明
所以注釋必須和源程序保持一致
假設一個方法共有兩個入參
但對應的Javadoc僅對其中一個入參用@param進行了說明
兩者出現了不一致
這時就出現了注釋沖突
JBuilder能夠檢查出這種不一致的沖突
結構窗格樹中將出現一個Javadoc Conflicts的文件夾
報告當前Java文件中所有的注釋沖突
如下圖所示
educity
cn/img_
/
/
/
jpg>
圖
Javadoc沖突報告
每條沖突注釋不但給出了沖突原因的簡要描述
還指定了沖突發生的位置
你可以點擊某沖突項
在彈出的對話框中選擇Fix Javadoc Conflict for
XXX
修復這個沖突
你也可以右擊Javadoc Conflicts文件夾
在彈出的菜單中選擇Fix Javadoc Conflicts修復全部的沖突
注意
Javadoc沖突只有在Errors文件夾中所有的語法錯誤都已經得到解決後才會報告出來
todo標簽
todo是JBuilder自定義的標簽
但它並不用於生成Javadoc文檔的內容
它相當於一個
助記符
表示此處有一個未完成的工作或一個待改進的工作
方便日後檢索和處理這些未盡之事
當前程序文件中的所有todo標簽歸結在結構窗格的To Do文件夾下
假設我們在Person
java中添加兩個todo標簽
如下所示
…
public class Person implements Serializable
{
public Person(String name
int sex) throws PersonArgumentException
{
if(sex != MALE && sex != FEMALE)
throw new PersonArgumentException(
參數不正確
);
/** @todo 還需做更多的校驗 */
this
name = name;
this
sex = sex;
}
…
/**
* 設置性別
* @param sex int
*/
public void setSex(int sex)
{
/** @todo 需要對入參做判斷 */
this
sex = sex;
}
}
在第
行添加上兩個todo標簽
todo標簽可以放在程序的任何地方
而不象Javadoc標簽一樣必須放置在類
接口
方法等定義語句的前面
此時
這兩個todo標簽都將出現在結構窗格的To Do文件夾下
如下圖所示
educity
cn/img_
/
/
/
jpg>
圖
To Do文件夾
點擊To Do文件夾下的項目
編輯器定位到代碼中相應的位置
如果你在工程的許多地方都插入了todo標簽
如何查看檢索查看它們呢？
From:http://tw.wingwit.com/Article/program/Java/hx/201311/26517.html
