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