熱點推薦:
您现在的位置: 電腦知識網 >> 編程 >> Java編程 >> Java核心技術 >> 正文

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

2013-11-23 19:14:37  來源: Java核心技術 

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