JBuilder 2005 Javadoc 進階：衝突檢測、TODO 標籤、自定義標籤與程式碼模板

JBuilder 提供強大的 Javadoc 輔助功能，不只產生文件，更能在撰寫階段提升品質。本文涵蓋衝突自動偵測、@todo 任務追蹤、自訂標籤擴充、程式碼模板加速輸入四大實用技巧。

1. Javadoc 衝突自動偵測

當註解與原始碼不一致（如方法有兩個參數但只寫一個 @param），結構窗格會出現 Javadoc Conflicts 資料夾，列出所有衝突位置與原因。

• 點擊單項 → Fix Javadoc Conflict for "XXX" 修復單一衝突。
• 右鍵資料夾 → Fix Javadoc Conflicts 一鍵修復全部。
• 注意：需先解決 Errors 資料夾所有語法錯誤，衝突才會顯示。

2. @todo 標籤：內建任務追蹤器

@todo 是 JBuilder 專屬標籤，不輸出到文件，僅作為「備忘記號」。

/** @todo 還需做更多的校驗 */
this.name = name;
/** @todo 需要對入參做判斷 */
this.sex = sex;

所有 @todo 自動彙整在結構窗格 To Do 資料夾，點擊即跳轉程式碼。專案層級查看：Search → View Todos，可關鍵字過濾。

3. 自訂 Javadoc 標籤：擴充文件語意

專案屬性 → Build → Javadoc → New... 建立自訂標籤：

• Tag name：notice
• Heading Text：文件顯示的標題（如「注意」）。
• Placement options：勾選所有元素類型。

使用範例：

/**@notice 這是用於表示性別的變量，合法值只能為MALE和FEMALE*/
protected int sex;

生成文件會出現「注意」區塊，內容為標籤後文字。

4. 程式碼模板：一鍵輸入標準註解區塊

Tools → Preferences → Editor → Templates → Common → Add...

• Template name: clscmt
• Description: class's comment
• Code 內容（含巨集）：

/**
 * 
|
 * @see
 * @version $Version, 2005-04-|
 * @author $Author
 * @since JDK1.3
 */

編輯器按 Ctrl+J 呼叫 clscmt，$Author/$Version 自動帶入專案屬性 General → class Javadoc fields 設定值。

小結

善用這四大功能，能讓 Javadoc 從「事後補充」變成「開發過程中的品質把關點」，大幅降低文件過時、遺漏、格式不一致的風險。