介绍：
    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 of the 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>
    /// <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生成注释的质量很大程度上取决于标识符命名的质量，

[1] [2] 下一页

所以长期使用ghostdoc，也会让你学会编写一致的和自解释的标识符，不亦乐乎？
ghostdoc不能做什么？
    ghostdoc很强大，但也不能对它有太高的期望。它生成注释的方式也许不能很好地符合你个人的注释风格。ghostdoc也不能一次性为整个代码文件生成注释，只能每次为一个成员生成注释——ghostdoc如此设计，是因为不管怎样总需要你去检查它生成的每段注释。
ghostdoc的配置：  
    在visual studio菜单栏中选择tools->ghostdoc->configure ghostdoc。
    其中包含如下几个属性页：
<!--[if !supportlists]--> <!--[endif]--><!--[if !supportlists]-->

rules    ： 修改，删除，添加文本生成规则
acronyms ： 指定将哪些单词视为首字母缩写词
"of the" reordering ： 指定触发重新排序行为的单词
"no the" words ： 指定哪些词前不使用”the”
options ： 配置ghostdoc的其它选项

上一页  [1] [2]