使用GhostDoc為程式碼生成註釋文件

iDotNetSpace發表於2008-06-24
介紹：
    GhostDoc是Visual Studio的一個免費外掛，可以幫助開發人員編寫XML格式的註釋文件。
    C#中XML格式的文件註釋好處多多：Visual Studio會在很多地方顯示這些註釋內容（例如，編輯器的工具提示或物件瀏覽器），還有一些工具（比如NDoc或微軟的文件工具Sandcastle）也可以利用這些註釋生成具有良好外觀的幫助檔案。這些都讓XML格式的註釋看上去很美——但很不幸，你首先得編寫大量簡單、乏味的註釋。
GhostDoc可以做什麼？    
    GhostDoc為Visual Studio中的C#程式碼編輯器安裝了一個新的命令。在編輯原始檔時，只需將游標置於要新增文件的方法或屬性內部，然後通過熱鍵（預設為Ctrl+Shift+D）或右鍵選單中的Document this選單項呼叫命令，GhostDoc就會插入一段XML格式的註釋。你也許會想到在方法或屬性前面鍵入"///"時的類似效果，但是後者只能建立一段空的註釋構造，而GhostDoc則能夠生成大部分實用的註釋。
    如果你的類成員是用於實現介面或重寫基類的成員，GhostDoc會使用既存的文件，不論這些介面或基類來自何處。這樣你就可以重用大量的微軟編寫的文件——是否想起了在實現IEumerable介面時，需要考慮如何為GetEnumerator()方法新增註釋。
    如果沒有既存的文件可用，GhostDoc會試著”猜測”如何為你生成註釋。這主意初看起來也許有點奇怪，不過在特定條件下（後面會提到）GhostDoc做的很不錯。有時候它”猜測”的結果會不太準確，甚至有些搞笑，但平均下來，修改這些生成的文件還是要比完全手工去寫省了不少時間。
    GhostDoc事實上並”不懂”英語，那為何它生成的文件卻常常令人相當滿意？其中的基本原理頗為簡單，GhostDoc假定你的程式碼遵從微軟類庫開發人員設計規範：
<!--[if !supportLists]--&gt<!--[endif]--&gt
  1. 你的程式碼使用Pascal或Camel命名法為由多個單片語成的識別符號命名
  2. 你的方法名通常以動詞開頭
  3. 你在識別符號中不使用縮寫
<!--[if !supportLists]--&gt<!--[endif]--&gt<!--[if !supportLists]--&gt<!--[endif]--&gt

        如果你能夠遵從這些規則（比如，使用ClearCache()而不是Clrcch()），同時使用一些自解釋的識別符號名稱，那麼GhostDoc就能派上用場了，它把識別符號分割為幾個單詞，將它們組合來生成註釋，也許並不完美，卻給你一個良好文件的開始。
        文字的生成使用可定製的規則和模板，除了內建的規則，還可以定義新的自定義規則來擴充套件或替換既有的規則（為你的自定義規則提供更高的優先順序或禁用內建規則）。
        上面提到過，GhostDoc並”不懂”英語，但它會嘗試使用某種機制來提高生成註釋的質量：

    <!--[if !supportLists]--&gt<!--[endif]--&gt
    1. 動詞的處理機制（GhostDoc假定方法名的首個單詞為動詞）：Add->Adds，Do->Does，Specify->Specifies；
    2. "Of the"排序組織機制：ColumnWidth -> Width of the column.
    3. 一些特殊形容詞的特殊合併機制：例如，MaximumColumnWidth->”Maximum width of the column”而不是”Width of the maximum column”
    4. 對首字母縮寫組成的常量的自動檢測，並通過一個列表來處理其它的一些首字母縮寫術語
    5. 使用一個單詞列表，以決定何時不使用”the”：AddItem -> Adds the item, BuildFromScratch -> Builds from scratch
    <!--[if !supportLists]--&gt<!--[endif]--&gt<!--[if !supportLists]--&gt<!--[endif]--&gt<!--[if !supportLists]--&gt<!--[if !supportLists]--&gt<!--[endif]--&gt
      下面是應用GhostDoc的一些例子：
      <!--

      Code highlighting produced by Actipro CodeHighlighter (freeware)
      http://www.CodeHighlighter.com/

      --&gt    /// 
                /// Determines the size of the page buffer.
                /// 
                /// Initial size of the page buffer.
                /// 
          public int DeterminePageBufferSize(int initialPageBufferSize)
          {
                    return 0;
          }

                /// 
                /// Adds the specified item.
                /// 
                /// The item.
          public void Add(string item)
          {
                    //does something
          }

                /// 
                /// Appends the HTML text.
                /// 
                /// The HTML provider.
          public void AppendHtmlText(IHtmlProvider htmlProvider)
          {
          }
          是不是驚人的準確？
          GhostDoc生成註釋的質量很大程度上取決於識別符號命名的質量，所以長期使用GhostDoc，也會讓你學會編寫一致的和自解釋的識別符號，不亦樂乎？
      GhostDoc不能做什麼？
          GhostDoc很強大，但也不能對它有太高的期望。它生成註釋的方式也許不能很好地符合你個人的註釋風格。GhostDoc也不能一次性為整個程式碼檔案生成註釋，只能每次為一個成員生成註釋——GhostDoc如此設計，是因為不管怎樣總需要你去檢查它生成的每段註釋。
      GhostDoc的配置：    
          在Visual Studio選單欄中選擇Tools->GhostDoc->Configure GhostDoc。

          其中包含如下幾個屬性頁：
      <!--[if !supportLists]--&gt <!--[endif]--&gt<!--[if !supportLists]--&gt

      1. Rules    ： 修改，刪除，新增文字生成規則
      2. Acronyms ： 指定將哪些單詞視為首字母縮寫詞
      3. "Of the" Reordering ： 指定觸發重新排序行為的單詞
      4. "No the" Words ： 指定哪些詞前不使用”the”
      5. Options ： 配置GhostDoc的其它選項

      來自 “ ITPUB部落格 ” ，連結：http://blog.itpub.net/12639172/viewspace-364703/，如需轉載，請註明出處，否則將追究法律責任。

      相關文章