C#.NET必备工具GhostDoc为代码生成注释文档

使用GhostDoc为代码生成注释文档

【转自www.bitsCN】

介绍：
    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

   /// <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

 

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

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

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

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

Options ： 配置GhostDoc的其它选项

下载链接：

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

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

巧用GhostDoc,实现自定义注释

使用GhostDoc可以帮我们生成比较完整规范的代码注释，如果变量命名规范的话，只需要按下Ctrl+Shift+D (默认热键)，由它自动产生的注释就已经完全可以很好地表达我们的创建方法或属性的目的，而不需要我们手动去修改注释了。除了这些以外，它的强大之处在于它的可订制性。我们完全可以通过规则定义定制我们需要的注释说明。下面图解如何定制注释。

在Vs 2005 Tools 菜单下打选择 GhostDoc 的下一级菜单项打开 GhostDoc 配置面板

 

 

 

选择Method 单击 Add 按钮添加一个规则。

 

在选择summary字段，单击在最后出现的按钮配置注释模板，【转自www.bitsCN】

双击选择宏变量：

一路OK返回。
   写一个方法测试一下.....光标移到方法名的位置按下Ctrl+Shit+D才会生效，在其它位置不会生成。
   同样的方法可以为属性，参数定义个性，并且导出当前的配置，以备下次重装后使用。

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

GhostDoc 安装与配置

1、GhostDoc1.2.1简介

GhostDoc 是一个基于Visual Studio的 XML 文档注释生成器，相比 NDoc 而言它更可以帮助你自动生成大量令人厌烦的相似的描述。

中国网管论坛bbs.bitsCN

2、安装（for VS2005）

在安装之前请确保关闭Visual Studio2005，双击GhostDoc2.1.1.msi进行安装

feedom

      

点击"Next"：

 

选 "I Agree" 点击"Next"：

中

选择要安装的路径，点击"Next"：

 

 

点击"Next"开始安装:

中

安装完成之后，出现如下图的窗口，

点击"Close"完成安装： 中国网管论坛bbs.bitsCN

 

 

3、配置

2.1、初步设置

打开Visual Studio 2005,出现如图对话框，如下图：

在此可以设置热键，点击"Assign",如果还不知道要把热键设成什么，或者要设的热键不在下拉菜单中，点击"Skip",之后再设。这里点击"Skip"，如下图: 网

 

如果是第一次安装GhostDoc，点击"Create"；

如果要载入已有的结构，点击"Import"(此处点击"Create")。出现如下窗口:

   

点击"Finish"完成，进入Visual Studio 2005界面，如下图：

        

      

在"工具"的下拉菜单里就会出现一个"GhostDoc"的选项，如下图： 

     

bitscn_com

右键菜单中就会出现"Document this"命令，如下图：

feedom

 

     

     

 

      

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 是一个值得一试的注释编写插件，它可以节省大量时间。