C 必備工具GhostDoc為代碼生成注釋文檔

1、使用GhostDoc為代碼生成注釋文檔【轉(zhuǎn)自 HYPERLINK http:/www.bitsCN.com】 www.bitsCN.com】介紹： GhostDoc是Visual Studio的一個(gè)免費(fèi)插件，可以幫助開發(fā)人員編寫XML格式的注釋文檔。 C#中XML格式的文檔注釋好處多多：Visual Studio會(huì)在很多地方顯示這些注釋內(nèi)容（例如，編輯器的工具提示或?qū)ο鬄g覽器），還有一些工具（比如NDoc或微軟的文檔工具Sandcastle）也可以利用這些注釋生成具有良好外觀的幫助文件。這些都讓XML格式的注釋看上去很美但很不幸，你首先得編寫大量簡單、乏味的注釋。GhostDoc可以做什么？

2、GhostDoc為Visual Studio中的C#代碼編輯器安裝了一個(gè)新的命令。在編輯源文件時(shí)，只需將光標(biāo)置于要添加文檔的方法或?qū)傩詢?nèi)部，然后通過熱鍵（默認(rèn)為Ctrl+Shift+D）或右鍵菜單中的Document this菜單項(xiàng)調(diào)用命令，GhostDoc就會(huì)插入一段XML格式的注釋。你也許會(huì)想到在方法或?qū)傩郧懊骀I入/時(shí)的類似效果，但是后者只能創(chuàng)建一段空的注釋構(gòu)造，而GhostDoc則能夠生成大部分實(shí)用的注釋。 如果你的類成員是用于實(shí)現(xiàn)接口或重寫基類的成員，GhostDoc會(huì)使用既存的文檔，不論這些接口或基類來自何處。這樣你就可以重用大量的微軟編寫的文檔是否想起了在實(shí)現(xiàn)IEumerable接

3、口時(shí)，需要考慮如何為GetEnumerator()方法添加注釋。 如果沒有既存的文檔可用，GhostDoc會(huì)試著”猜測”如何為你生成注釋。這主意初看起來也許有點(diǎn)奇怪，不過在特定條件下（后面會(huì)提到）GhostDoc做的很不錯(cuò)。有時(shí)候它”猜測”的結(jié)果會(huì)不太準(zhǔn)確，甚至有些搞笑，但平均下來，修改這些生成的文檔還是要比完全手工去寫省了不少時(shí)間。 GhostDoc事實(shí)上并”不懂”英語，那為何它生成的文檔卻常常令人相當(dāng)滿意？其中的基本原理頗為簡單，GhostDoc假定你的代碼遵從微軟類庫開發(fā)人員設(shè)計(jì)規(guī)范：你的代碼使用Pascal或Camel命名法為由多個(gè)單詞組成的標(biāo)識(shí)符命名你的方法名通常以動(dòng)詞開頭你在標(biāo)識(shí)符

4、中不使用縮寫 如果你能夠遵從這些規(guī)則（比如，使用ClearCache()而不是Clrcch()），同時(shí)使用一些自解釋的標(biāo)識(shí)符名稱，那么GhostDoc就能派上用場了，它把標(biāo)識(shí)符分割為幾個(gè)單詞，將它們組合來生成注釋，也許并不完美，卻給你一個(gè)良好文檔的開始。 文本的生成使用可定制的規(guī)則和模板，除了內(nèi)置的規(guī)則，還可以定義新的自定義規(guī)則來擴(kuò)展或替換既有的規(guī)則（為你的自定義規(guī)則提供更高的優(yōu)先級(jí)或禁用內(nèi)置規(guī)則）。 上面提到過，GhostDoc并”不懂”英語，但它會(huì)嘗試使用某種機(jī)制來提高生成注釋的質(zhì)量： 動(dòng)詞的處理機(jī)制（GhostDoc假定方法名的首個(gè)單詞為動(dòng)詞）：Add-Adds，Do-Does，Spec

5、ify-Specifies；Of the排序組織機(jī)制：ColumnWidth - Width of the column.一些特殊形容詞的特殊合并機(jī)制：例如，MaximumColumnWidth-”Maximum width of the column”而不是”Width of the maximum column”對(duì)首字母縮寫組成的常量的自動(dòng)檢測，并通過一個(gè)列表來處理其它的一些首字母縮寫術(shù)語使用一個(gè)單詞列表，以決定何時(shí)不使用”the”：AddItem - Adds the item, BuildFromScratch - Builds from scratch下面是應(yīng)用GhostDoc的一些

6、例子： / / 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. pub

7、lic void AppendHtmlText(IHtmlProvider htmlProvider) 是不是驚人的準(zhǔn)確？ GhostDoc生成注釋的質(zhì)量很大程度上取決于標(biāo)識(shí)符命名的質(zhì)量，所以長期使用GhostDoc，也會(huì)讓你學(xué)會(huì)編寫一致的和自解釋的標(biāo)識(shí)符，不亦樂乎？GhostDoc不能做什么？ GhostDoc很強(qiáng)大，但也不能對(duì)它有太高的期望。它生成注釋的方式也許不能很好地符合你個(gè)人的注釋風(fēng)格。GhostDoc也不能一次性為整個(gè)代碼文件生成注釋，只能每次為一個(gè)成員生成注釋GhostDoc如此設(shè)計(jì)，是因?yàn)椴还茉鯓涌傂枰闳z查它生成的每段注釋。GhostDoc的配置： 在Visual Stud

8、io菜單欄中選擇Tools-GhostDoc-Configure GhostDoc。 其中包含如下幾個(gè)屬性頁： Rules ： 修改，刪除，添加文本生成規(guī)則Acronyms ： 指定將哪些單詞視為首字母縮寫詞Of the Reordering ： 指定觸發(fā)重新排序行為的單詞No the Words ： 指定哪些詞前不使用”the”O(jiān)ptions ： 配置GhostDoc的其它選項(xiàng)下載鏈接：http:/submai/download/GhostDoc_v2.5.zip巧用GhostDoc,實(shí)現(xiàn)自定義注釋使用GhostDoc可以幫我們生成比較完整規(guī)范的代碼注釋，如果變量命名規(guī)范的話，只需要按下Ct

9、rl+Shift+D (默認(rèn)熱鍵)，由它自動(dòng)產(chǎn)生的注釋就已經(jīng)完全可以很好地表達(dá)我們的創(chuàng)建方法或?qū)傩缘哪康?，而不需要我們手?dòng)去修改注釋了。除了這些以外，它的強(qiáng)大之處在于它的可訂制性。我們完全可以通過規(guī)則定義定制我們需要的注釋說明。下面圖解如何定制注釋。在Vs 2005 Tools 菜單下打選擇 GhostDoc 的下一級(jí)菜單項(xiàng)打開 GhostDoc 配置面板選擇Method 單擊 Add 按鈕添加一個(gè)規(guī)則。在選擇summary字段，單擊在最后出現(xiàn)的按鈕配置注釋模板， 【轉(zhuǎn)自 HYPERLINK http:/www.bitsCN.com】 www.bitsCN.com】雙擊選擇宏變量：一路OK返回

10、。寫一個(gè)方法測試一下光標(biāo)移到方法名的位置按下Ctrl+Shit+D才會(huì)生效，在其它位置不會(huì)生成。同樣的方法可以為屬性，參數(shù)定義個(gè)性，并且導(dǎo)出當(dāng)前的配置，以備下次重裝后使用。GhostDoc 安裝與配置1、GhostDoc1.2.1簡介 GhostDoc 是一個(gè)基于Visual Studio的 XML 文檔注釋生成器，相比 NDoc 而言它更可以幫助你自動(dòng)生成大量令人厭煩的相似的描述。 中國網(wǎng)管論壇bbs.bitsCN.com2、安裝（for VS2005） 在安裝之前請(qǐng)確保關(guān)閉Visual Studio2005，雙擊GhostDoc2.1.1.msi進(jìn)行安裝 點(diǎn)擊Next： 選 I Agree

11、 點(diǎn)擊Next： 中 選擇要安裝的路徑，點(diǎn)擊Next： 點(diǎn)擊Next開始安裝: 中安裝完成之后，出現(xiàn)如下圖的窗口，點(diǎn)擊Close完成安裝： 中國網(wǎng)管論壇bbs.bitsCN.com 3、配置 2.1、初步設(shè)置 打開Visual Studio 2005,出現(xiàn)如圖對(duì)話框，如下圖： 在此可以設(shè)置熱鍵，點(diǎn)擊Assign,如果還不知道要把熱鍵設(shè)成什么，或者要設(shè)的熱鍵不在下拉菜單中，點(diǎn)擊Skip,之后再設(shè)。這里點(diǎn)擊Skip，如下圖: 網(wǎng) 如果是第一次安裝GhostDoc，點(diǎn)擊Create； 如果要載入已有的結(jié)構(gòu)，點(diǎn)擊Import(此處點(diǎn)擊Create)。出現(xiàn)如下窗口: 點(diǎn)擊Finish完成，進(jìn)入Visua

12、l Studio 2005界面，如下圖： 在工具的下拉菜單里就會(huì)出現(xiàn)一個(gè)GhostDoc的選項(xiàng)，如下圖： bitscn_com 右鍵菜單中就會(huì)出現(xiàn)Document this命令，如下圖： 2.2、GhostDoc的配置 在Visual Studio2005的菜單欄中選擇工具|GhostDoc|Configure GhostDoc，彈出對(duì)話框如下圖： 其中包含的屬性頁： 1. Rules 修改，刪除，添加文本生成規(guī)則 2. Acronyms 指定將哪些單詞視為首字母縮寫詞 3. of theReordering 指定觸發(fā)重新排序行為的單詞 4. No theWords 指定哪些詞前不使用the

13、5. Options 配置GhostDoc的其他選項(xiàng) GhostDoc 自動(dòng)生成 XML 注釋將 XML 注釋迅速添加到 Visual Studio 項(xiàng)目中Microsoft .NET Framework 通過 XML 注釋簡化了記錄類、方法、屬性及事件的任務(wù)。XML 注釋是嵌入到源代碼注釋中的特殊 XML 標(biāo)記，提供類及其成員的相關(guān)元數(shù)據(jù)。在編譯過程中，此元數(shù)據(jù)會(huì)由 Visual Studio 轉(zhuǎn)換為獨(dú)立的 XML 文件，然后通過使用 Microsoft Sandcastle project 之類的工具轉(zhuǎn)換為幫助文件。GhostDoc 會(huì)自動(dòng)生成 XML 注釋(單擊該圖像獲得較大視圖)當(dāng) X

14、ML 注釋協(xié)助將源代碼注釋自動(dòng)轉(zhuǎn)換為 RTF 幫助文檔時(shí)，仍須寫入注釋文本，這是一項(xiàng)令很多開發(fā)人員感到精疲力盡的工作。為什么不使用自動(dòng)化來加速這些注釋的創(chuàng)建呢？這正是 GhostDoc 1.9.5 試圖實(shí)現(xiàn)的目標(biāo)。GhostDoc 是一個(gè)免費(fèi)的 Visual Studio 加載項(xiàng)，由 Roland Weigelt 創(chuàng)建，用來協(xié)助編寫 XML 注釋。一旦安裝了 GhostDoc，只要使用它指一指、點(diǎn)一點(diǎn)，就能輕松地自動(dòng)生成 XML 注釋。例如，若要將 XML 注釋添加到某個(gè)方法中，只需在該方法中右鍵單擊，然后從上下文菜單中選擇“Document This”選項(xiàng)。GhostDoc 就會(huì)根據(jù)該方法的類型、參數(shù)、名稱和其他上下文信息為其自動(dòng)生成 XML 注釋文本。如果您正在 .NET Framework 中為使用某個(gè)類型的屬性或方法生成文檔，則 GhostDoc 將會(huì)使用 Microsoft 已為該類型編寫的文檔。如果您使用 Pascal 大小寫格式或 Camel 大小寫