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

Posted Snowdust

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了使用GhostDoc为代码生成注释文档相关的知识,希望对你有一定的参考价值。

介绍:ITPUB个人空间;q$Vei3@4h,i
    GhostDoc是Visual Studio的一个免费插件,可以帮助开发人员编写XML格式的注释文档。
)XO&w'Kon(z;Q0    C#中XML格式的文档注释好处多多:Visual Studio会在很多地方显示这些注释内容(例如,编辑器的工具提示或对象浏览器),还有一些工具(比如NDoc或微软的文档工具Sandcastle)也可以利用这些注释生成具有良好外观的帮助文件。这些都让XML格式的注释看上去很美——但很不幸,你首先得编写大量简单、乏味的注释。ITPUB个人空间3g.q3wq'g
GhostDoc可以做什么?   ITPUB个人空间F6n!W.?7g,d:/j
    GhostDoc为Visual Studio中的C#代码编辑器安装了一个新的命令。在编辑源文件时,只需将光标置于要添加文档的方法或属性内部,然后通过热键(默认为Ctrl+Shift+D)或右键菜单中的Document this菜单项调用命令,GhostDoc就会插入一段XML格式的注释。你也许会想到在方法或属性前面键入"///"时的类似效果,但是后者只能创建一段空的注释构造,而GhostDoc则能够生成大部分实用的注释。ITPUB个人空间 S@(mJ v8]mB
    如果你的类成员是用于实现接口或重写基类的成员,GhostDoc会使用既存的文档,不论这些接口或基类来自何处。这样你就可以重用大量的微软编写的文档——是否想起了在实现IEumerable接口时,需要考虑如何为GetEnumerator()方法添加注释。
5Ytat 0    如果没有既存的文档可用,GhostDoc会试着”猜测”如何为你生成注释。这主意初看起来也许有点奇怪,不过在特定条件下(后面会提到)GhostDoc做的很不错。有时候它”猜测”的结果会不太准确,甚至有些搞笑,但平均下来,修改这些生成的文档还是要比完全手工去写省了不少时间。ITPUB个人空间o0MQ Ko+AF GQ
    GhostDoc事实上并”不懂”英语,那为何它生成的文档却常常令人相当满意?其中的基本原理颇为简单,GhostDoc假定你的代码遵从微软类库开发人员设计规范
?m)U*fIw8_/f1g0<!--[if !supportLists]--><!--[endif]-->

  1. 你的代码使用Pascal或Camel命名法为由多个单词组成的标识符命名
  2. 你的方法名通常以动词开头
  3. 你在标识符中不使用缩写

<!--[if !supportLists]--><!--[endif]--><!--[if !supportLists]--><!--[endif]-->

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

<!--[if !supportLists]--><!--[endif]-->

  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

<!--[if !supportLists]--><!--[endif]--><!--[if !supportLists]--><!--[endif]--><!--[if !supportLists]--><!--[if !supportLists]--><!--[endif]-->

下面是应用GhostDoc的一些例子:ITPUB个人空间3p#CO oE2gw7v

     ///   <summary> ITPUB个人空间9d(ZOf%I)oz/
    
///  Determines the size of the page buffer.
,K^ZZ3TK)/'A[m0    
///   </summary>
%wV3z-oH@Y0    
///   <param name="initialPageBufferSize"> Initial size of the page buffer. </param> ITPUB个人空间@*O3k'D iR
    
///   <returns></returns> ITPUB个人空间 k `j@@b,z!n
     public   int  DeterminePageBufferSize( int  initialPageBufferSize)ITPUB个人空间CF x9S KHZ
    ITPUB个人空间+kc.y MN&Mu
        
return   0 ;
6B;Q U#Xa9a1~TS0    ITPUB个人空间u6g:n]M
ITPUB个人空间%w&i(cMm I*IC(G
    
///   <summary>
:C)l!y6fb%e.Uc:I1Yc0    
///  Adds the specified item.ITPUB个人空间;fI2G6cB ?3`'1D
    
///   </summary> ITPUB个人空间"k(a[.V'Le,l e(V
    
///   <param name="item"> The item. </param> ITPUB个人空间XH*AU(B?T%n f
     public   void  Add( string  item)ITPUB个人空间W&e$T4p ~
    
$X*z;Dh/B)e(q3H0        
//does something
o1]/+ui_ ~&x0
    ITPUB个人空间 ti /o'a A ^|

7l3O4V)jFv;DY0    
///   <summary>
~:Uo?3gBd-W8h0    
///  Appends the html text.ITPUB个人空间cSn*?Y r
    
///   </summary> ITPUB个人空间-P*z+]Ln,]
    
///   <param name="htmlProvider"> The HTML provider. </param>
@%Q'D'f;g ^LyF0
     public   void  AppendHtmlText(IHtmlProvider htmlProvider)ITPUB个人空间I rd&[0"v5Ai
    ITPUB个人空间Z&jX/$e
    

    是不是惊人的准确?ITPUB个人空间"n7e1KKE R /:P
    GhostDoc生成注释的质量很大程度上取决于标识符命名的质量,所以长期使用GhostDoc,也会让你学会编写一致的和自解释的标识符,不亦乐乎?ITPUB个人空间)v:Zx4S h8S T5Qu|
GhostDoc不能做什么?ITPUB个人空间Ar:l+B4t5s
    GhostDoc很强大,但也不能对它有太高的期望。它生成注释的方式也许不能很好地符合你个人的注释风格。GhostDoc也不能一次性为整个代码文件生成注释,只能每次为一个成员生成注释——GhostDoc如此设计,是因为不管怎样总需要你去检查它生成的每段注释。ITPUB个人空间/y8^9i!Zpa
GhostDoc的配置:   ITPUB个人空间+w!c8[wOV)j2D
    在Visual Studio菜单栏中选择Tools->GhostDoc->Configure GhostDoc。

    其中包含如下几个属性页:
x$S,l0D8rF~mW0NCN0<!--[if !supportLists]--> <!--[endif]--><!--[if !supportLists]-->

  1. Rules    : 修改,删除,添加文本生成规则
  2. Acronyms : 指定将哪些单词视为首字母缩写词
  3. "Of the" Reordering : 指定触发重新排序行为的单词
  4. "No the" Words : 指定哪些词前不使用”the”
  5. Options : 配置GhostDoc的其它选项

 

以上是关于使用GhostDoc为代码生成注释文档的主要内容,如果未能解决你的问题,请参考以下文章

我可以使用 GhostDoc 将文档添加到整个类或代码文件吗?

如何从 GhostDoc 规则中删除 XML 注释元素?

GhostDoc“记录此”不适用于具有属性的方法

用 Visual Studio 自动生成C/C++注释(DoxygenXML)

将 GhostDoc 文档移动到 <include> 标记文件

Ghostdoc 不会尝试生成返回信息