C#.NET必備工具GhostDoc為代碼產生注釋文檔

使用GhostDoc為代碼產生注釋文檔

【轉自www.bitsCN.com】

介紹：
    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]--><!--[endif]-->
你的代碼使用Pascal或Camel命名法為由多個單片語成的標識符命名
你的方法名通常以動詞開頭
你在標識符中不使用縮寫
<!--[if !supportLists]--><!--[endif]--><!--[if!supportLists]--><!--[endif]-->
    如果你能夠遵從這些規則（比如，使用ClearCache()而不是Clrcch()），同時使用一些自解釋的標識符名稱，那麼GhostDoc就能派上用場了，它把標識符分割為幾個單詞，將它們組合來產生注釋，也許並不完美，卻給你一個良好文檔的開始。
    文本的產生使用可定製的規則和模板，除了內建的規則，還可以定義新的自訂規則來擴充或替換既有的規則（為你的自訂規則提供更高的優先順序或禁用內建規則）。

 

    上面提到過，GhostDoc並”不懂”英語，但它會嘗試使用某種機制來提高產生注釋的品質：   

<!--[if!supportLists]--><!--[endif]-->
動詞的處理機制（GhostDoc假定方法名的首個單詞為動詞）：Add->Adds，Do->Does，Specify->Specifies；
"Of the"排序組織機制：ColumnWidth -> Width of the column.
一些特殊形容詞的特殊合并機制：例如，MaximumColumnWidth->”Maximum width ofthe column”而不是”Width of the maximum column”
對首字母縮寫組成的常量的自動檢測，並通過一個列表來處理其它的一些首字母縮寫術語
使用一個單字清單，以決定何時不使用”the”：AddItem ->Adds the item, BuildFromScratch -> Builds from scratch
<!--[if !supportLists]--><!--[endif]--><!--[if!supportLists]--><!--[endif]--><!--[if!supportLists]--><!--[if !supportLists]--><!--[endif]-->
下面是應用GhostDoc的一些例子：
    /// <summary>
    /// Determines the size of the page buffer.
    /// </summary>
    /// <paramname="initialPageBufferSize">Initial size of the pagebuffer.</param>    /// <returns></returns>
    public int DeterminePageBufferSize(intinitialPageBufferSize)
    {
        return 0;
    }

      

   /// <summary>
    /// Adds the specified item.
    /// </summary>
    /// <param name="item">Theitem.</param>
    public void Add(string item)
    {
        //does something
    } bitscn.com

   /// <summary>
    /// Appends the HTML text.
    /// </summary>
    /// <param name="htmlProvider">The HTMLprovider.</param>
    public void AppendHtmlText(IHtmlProvider htmlProvider)
    {
    }    是不是驚人的準確。
    GhostDoc產生注釋的品質很大程度上取決於標識符命名的品質，

所以長期使用GhostDoc，也會讓你學會編寫一致的和自解釋的標識符，不亦樂乎。

GhostDoc不能做什麼。

   GhostDoc很強大，但也不能對它有太高的期望。它產生注釋的方式也許不能很好地符合你個人的注釋風格。GhostDoc也不能一次性為整個代碼檔案產生注釋，只能每次為一個成員產生注釋——GhostDoc如此設計，是因為不管怎樣總需要你去檢查它產生的每段注釋。

GhostDoc的配置：  

    在VisualStudio功能表列中選擇Tools->GhostDoc->Configure GhostDoc。

    其中包含如下幾個屬性頁面：

<!--[if !supportLists]--><!--[endif]--><!--[if !supportLists]--> bitscn.com

 

Rules   ：修改，刪除，添加文本建置規則

Acronyms ： 指定將哪些單詞視為首字母縮寫詞

"Of the" Reordering ： 指定觸發重新排序行為的單詞

"No the" Words ： 指定哪些詞前不使用”the”

Options ： 配置GhostDoc的其它選項

下載連結：

http://submain.com/download/GhostDoc_v2.5.zip

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

巧用GhostDoc,實現自訂注釋

使用GhostDoc可以幫我們產生比較完整規範的代碼注釋，如果變數命名規範的話，只需要按下Ctrl+Shift+D (預設熱鍵)，由它自動產生的注釋就已經完全可以很好地表達我們的建立方法或屬性的目的，而不需要我們手動去修改注釋了。除了這些以外，它的強大之處在於它的可訂製性。我們完全可以通過規則定義定製我們需要的注釋說明。下面圖解如何定製注釋。

在Vs 2005 Tools 菜單下打選擇 GhostDoc 的下一級功能表項目開啟 GhostDoc 配置面板

 

 

 

選擇Method 單擊 Add 按鈕添加一個規則。

 

在選擇summary欄位，單擊在最後出現的按鈕配置注釋模板，【轉自www.bitsCN.com】

雙擊選擇宏變數：

一路OK返回。
   寫一個方法測試一下.....游標移到方法名的位置按下Ctrl+Shit+D才會生效，在其它位置不會產生。
   同樣的方法可以為屬性，參數定義個性，並且匯出當前的配置，以備下次重裝後使用。

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

GhostDoc 安裝與配置

1、GhostDoc1.2.1簡介

GhostDoc 是一個基於Visual Studio的 XML 文件註解產生器，相比 NDoc 而言它更可以協助你自動產生大量令人厭煩的相似的描述。

中國網管論壇bbs.bitsCN.com

2、安裝（for VS2005）

在安裝之前請確保關閉Visual Studio2005，雙擊GhostDoc2.1.1.msi進行安裝

feedom.net

      

點擊"Next"：

 

選 "I Agree" 點擊"Next"：

中

選擇要安裝的路徑，點擊"Next"：

 

 

點擊"Next"開始安裝:

中

安裝完成之後，出現如下圖的視窗，

點擊"Close"完成安裝： 中國網管論壇bbs.bitsCN.com

 

  3、配置 2.1、初步設定

開啟Visual Studio 2005,出現如圖對話方塊，如下圖：

在此可以設定熱鍵，點擊"Assign",如果還不知道要把熱鍵設成什麼，或者要設的熱鍵不在下拉式功能表中，點擊"Skip",之後再設。這裡點擊"Skip"，如下圖: 網

 

如果是第一次安裝GhostDoc，點擊"Create"；

如果要載入已有的結構，點擊"Import"(此處點擊"Create")。出現如下視窗:

   

點擊"Finish"完成，進入Visual Studio 2005介面，如下圖：

        

      

在"工具"的下拉式功能表裡就會出現一個"GhostDoc"的選項，如下圖： 

     

bitscn_com

右鍵菜單中就會出現"Document this"命令，如下圖：

feedom.net

 

     

     

 

       2.2、GhostDoc的配置

在Visual Studio2005的功能表列中選擇"工具|GhostDoc|Configure GhostDoc"，彈出對話方塊如下圖：

      

其中包含的屬性頁面：     

1. Rules 修改，刪除，添加文本建置規則

 

2. Acronyms 指定將哪些單詞視為首字母縮寫詞

3. "of the"Reordering 指定觸發重新排序行為的單詞    

4. "No the"Words 指定哪些詞前不使用"the"         

5. Options 配置GhostDoc的其他選項

GhostDoc 自動產生XML 注釋

將 XML 注釋迅速添加到 Visual Studio 項目中

Microsoft® .NET Framework 通過 XML 注釋簡化了記錄類、方法、屬性及事件的任務。XML 注釋是嵌入到原始碼注釋中的特殊 XML 標記，提供類及其成員的相關中繼資料。在編譯過程中，此中繼資料會由 Visual Studio®轉換為獨立的 XML 檔案，然後通過使用Microsoft Sandcastle project之類的工具轉換為協助檔案。

GhostDoc 會自動產生 XML 注釋(單擊該映像獲得較大視圖)

當 XML 注釋協助將原始碼注釋自動轉換為 RTF 協助文檔時，仍須寫入注釋文本，這是一項令很多開發人員感到精疲力盡的工作。為什麼不使用自動化來加速這些注釋的建立呢。這正是 GhostDoc 1.9.5 試圖實現的目標。

GhostDoc 是一個免費的 Visual Studio 附加元件，由 Roland Weigelt 建立，用來協助編寫 XML 注釋。一旦安裝了 GhostDoc，只要使用它指一指、點一點，就能輕鬆地自動產生 XML 注釋。例如，若要將 XML 注釋添加到某個方法中，只需在該方法中按右鍵，然後從操作功能表中選擇“Document This”選項。

GhostDoc 就會根據該方法的類型、參數、名稱和其他上下文資訊為其自動產生 XML 注釋文本。

如果您正在 .NET Framework 中為使用某個類型的屬性或方法產生文檔，則 GhostDoc 將會使用 Microsoft 已為該類型編寫的文檔。如果您使用 Pascal 大小寫格式或 Camel 大小寫格式，GhostDoc 可將該名稱拆分成幾個單詞，並分析這些單獨的單詞，以產生文檔。所有的文檔邏輯都按照 GhostDoc 的建置規則來處理。既可以對這些內建規則進行自訂，也可以添加新的規則。還可以匯出這些規則，以便在其他電腦上使用。

除最簡單的成員外，您不能完全依賴 GhostDoc 為您編寫 XML 注釋。GhostDoc 自動產生的注釋只是建議，還需開發人員進行審核。無論如何，GhostDoc 是一個值得一試的注釋編寫外掛程式，它可以節省大量時間。