VS工具--GhostDoc

一、介绍：
    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假定你的代码遵从微软类库开发人员设计规范： 

1. 你的代码使用Pascal或Camel命名法为由多个单词组成的标识符命名

2. 你的方法名通常以动词开头

3. 你在标识符中不使用缩写

    如果你能够遵从这些规则（比如，使用ClearCache()而不是Clrcch()），同时使用一些自解释的标识符名称，那么GhostDoc就能派上用场了，它把标识符分割为几个单词，将它们组合来生成注释，也许并不完美，却给你一个良好文档的开始。
    文本的生成使用可定制的规则和模板，除了内置的规则，还可以定义新的自定义规则来扩展或替换既有的规则（为你的自定义规则提供更高的优先级或禁用内置规则）。
    上面提到过，GhostDoc并”不懂”英语，但它会尝试使用某种机制来提高生成注释的质量：

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

下面是应用GhostDoc的一些例子： 

    /// <summary>
    /// Determines the size of the page buffer.
    /// </summary>
    /// <param name="initialPageBufferSize">Initial size of the page buffer.</param>
    /// <returns></returns>
    public int DeterminePageBufferSize(int initialPageBufferSize)
    {
        return 0;
    }

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

    /// <summary>
    /// Appends the HTML text.
    /// </summary>
    /// <param name="htmlProvider">The HTML provider.</param>
    public void AppendHtmlText(IHtmlProvider htmlProvider)
    {
    }

    是不是惊人的准确？
    GhostDoc生成注释的质量很大程度上取决于标识符命名的质量，所以长期使用GhostDoc，也会让你学会编写一致的和自解释的标识符，不亦乐乎？
GhostDoc不能做什么？ 
    GhostDoc很强大，但也不能对它有太高的期望。它生成注释的方式也许不能很好地符合你个人的注释风格。GhostDoc也不能一次性为整个代码文件生成注释，只能每次为一个成员生成注释——GhostDoc如此设计，是因为不管怎样总需要你去检查它生成的每段注释。 
GhostDoc的配置：     
    在Visual Studio菜单栏中选择Tools->GhostDoc->Configure GhostDoc。

    其中包含如下几个属性页：

1. Rules    ： 修改，删除，添加文本生成规则

2. Acronyms ： 指定将哪些单词视为首字母缩写词

3. "Of the" Reordering ： 指定触发重新排序行为的单词

4. "No the" Words ： 指定哪些词前不使用”the”

5. Options ： 配置GhostDoc的其它选项

    GhostDoc下载地址：http://www.roland-weigelt.de/ghostdoc
    参考原文地址：roland-weight的文章

　　三、安装

　　下载安装完成后，可以在Visual Studio的工具菜单下找到GhostDoc的身影。

　　

　　在第一次使用时，会要求设置快捷键，默认的是Ctrl+Shift+S，如果这和你设置的快捷键有所冲突的话，可以在选择的下拉列表里另外选择一个。

　　GhostDoc使用的优点自然是可以快速生成注释，提高开发效率，但是缺点也不少，首先她生成的注释都是英文，难免有时看的会不顺眼，而且有时会无法生成准确的注释，原因在于 GhostDoc生成注释的质量很大程度上取决于标识符命名的质量，比如方法用Pascal命名法，变量用Camel命名法等，所以使用GhostDoc也可以变向的检查一下你的命名是否合理，是否足够见名之意。

　　如果你的类成员是用于实现接口或重写基类的成员，GhostDoc会使用既存的文档，不论这些接口或基类来自何处，如果没有既存的文档可用，GhostDoc会试着”猜测”如何为你生成注释，当然准确性可能就要看RP了。。。

　　四、使用

　　1、如果无法识别出变量的名字，GhostDoc就只会生成summary的标签，此时光标会移到空白的注释内容上：

　　

　　2、有时生成的注释会不准确，或者不符合个人的习惯：

　　

　　3、如果命名合理，当然还是能够准确的生成注释的：

　　

　　五、自定义配置

　　　　除了简单的使用之外，还可以去GhostDoc中去进行自定义配置：

　　

　　配置的方法在安装目录下有一个GhostDoc的帮助文档，可以按照文档进行详细设置，这里就简单举个例子好了：

　　1、先说最后一个Options选项卡，因为感觉比较实用有些，这里可以自动生成附加注释，这里有一个CustomText的文本框，这里既可以输出自己想要的注释，也可以点击旁边的按钮使用系统已定义的宏变量，如下所示：

　　

　　这样生成的注释如下：

　　

　　呵呵，感觉不错。。　　

　　2、下面说说第一个“规则”选项卡，也是最重要的一个，这里随便点开一个有代表性的：

　　　　

　　在描述可以看到这个规则会检测返回的一个以can开头的布尔值，下面是返回的模板和生成的summary注释模板，这里有着最高优先级的会出现在第一个，如果没有匹配第一个的就依次向下查找。

　　这里可能是配置最复杂但也需求最多的地方，就以添加一个简单的个性方法为例吧：

　　在Methods上点击Add，然后随便填入一个你喜欢的名字，随后进入Method配置：

　　

　　配置完成后，可以在下面进行个简单的测试。 

　　随后进入type配置：

　　

　　需要的还可以进行参数配置，方法都是大同小异的。 

　　随后配置summary标签的模板，比如：

　　

　　或者可以点击后面的按钮选择系统自定义的宏。

　　配置好了，下面来看看结果:

　　

　　得到了我们想要的结果。

　　3、第二个选项卡是缩写词的设置，这里指的是GhostDoc会尝试检测的首字母缩写，比如BuildHtmlText()方法中的Html会被解释成HTML，但其只自动处理辅音字幕，而其他的词则必须在这个对话框选项卡的配置表进行。

　　比如：

　　

　　　　随后在规则中添加UML，重新生成注释如下：

　　

　　4、"Of the"规则：比如这里定义了size，那么类似"FileBufferSize"的词就会注释成"Size of the file buffer"，貌似俺没有啥需要自定义的了。。。

　　5、"No the" Word：在GhostDoc创建注释时会在标识名前创建一个the，而这个选项卡的列表中显示的内容则不会创建，效果如下：

　　　　没有添加规则时：

　　

　　　　添加myx进入此规则，重新生成注释：

　　

　　这个貌似有些无关痛痒，估计也就老外也会对这个the有些在意，所以才整了这么一个规则。。。

　　六、其他技巧示例

　　GhostDoc会自动检测到继承和重写的方法注释，这也大大简化了操作。

　　例一：继承

 　 这里定义一个简单的属性，看看注释的效果：

　　

　　再看看重写时注释的效果：

　　

　　哈哈，已经可以得到我们之前注释的内容了。。。

　　这里需要注意的是：必须使用summary注释标签，简单的 // 注释GhostDoc是不会理睬的。。。

　　

　　例二：重写

 　　如果你要硬说GhostDoc不能生成中文的注释，那也是不对的，其实如果你装的是中文版的VS，那么完全是可以生成中文的注释的，比如这里我们

 继承了System.Web.UI下面的ControlBuilder类，并准备重写HtmlDecodeLiterals()方法，先看一下VS现在的智能提示： 

　　现在生成注释，看看效果：