[转]新版.NET开发必备十大工具
摘要
在新版.Net开发必备十大工具一文中,笔者整理总结了.NET平台下开发必备的十大工具,在本篇文章中,我将详细介绍自动生成文档注释工具GhostDoc。
工具介绍
GhostDoc是Visual Studio的一个免费插件,可以帮助开发者生成比较完整规范的XML格式代码注释,如果你的代码遵循微软类库开发人员设计规范 ,由它自动产生的注释就已经完全可以很好地表达开发者创建的方法或者属性的意图,无需手工再进行修改。有了这些标准的XML注释,我们可以使用微软的文档工具Sandcastle生成专业级别的帮助文档。
使用场景
自动为我们编写的代码产生标准的XML注释。
安装配置
在运行GhostDoc2.1.3 for Visual Studio 2008之后,安装步骤基本上按照默认的方式进行,如下图所示:
安装进度:
在安装过程中,注意需要关闭Visual Studio 2008,否则将不能正确安装。在安装完成后,第一次启动Visual Studio将会提示你进行GhostDoc配置,如设置热键等,这些都可以默认,不用做特殊设置。一会儿我们将会进行GhostDoc的配置。
基本使用
在安装完GhostDoc之后,在Visual Studio工具菜单中可以看到GhostDoc这样一项。
首先我们编写一段简单的代码,如下所示:
1: public bool Add(string item)
2: {
3: //......
4: }
5:
6: public bool Remove(string item)
7: {
8: //......
9: }
10:
11: public void AppendHtmlText(IHtmlProvider htmlProvider)
12: {
13: //......
14: }
当鼠标光标放在方法上时,按下热键Ctrl + Shift + D将会生成注释,如下所示:
1: /// <summary>
2: /// Adds the specified item.
3: /// </summary>
4: /// <param name="item">The item.</param>
5: /// <returns></returns>
6: public bool Add(string item)
7: {
8: //......
9: }
10:
11: /// <summary>
12: /// Removes the specified item.
13: /// </summary>
14: /// <param name="item">The item.</param>
15: /// <returns></returns>
16: public bool Remove(string item)
17: {
18: //......
19: }
20:
21: /// <summary>
22: /// Appends the HTML text.
23: /// </summary>
24: /// <param name="htmlProvider">The HTML provider.</param>
25: public void AppendHtmlText(IHtmlProvider htmlProvider)
26: {
27: //......
28: }
或者我们可以选择菜单Tools->GhostDoc->Document this菜单,如下图所示:
大家看看上面的生成的注释,是不是非常的准确?但是有一点是可以肯定的,GhostDoc肯定不懂英文:),那它是如何生成如此准确的注释文档的呢?简单来说,就一点,GhostDoc假定你的代码符合微软.NET类库设计准则(不知道大家记起来什么了没有?没错,就是在上一篇中我们介绍的代码分析工具,使用这个工具可以检查你的代码是否符合.NET类库设计准则)。GhostDoc其实就是拆分标识符,然后重新组合而生成注释,所以GhostDoc与Source Analysis for C#可谓是绝配。
配置GhostDoc
GhostDoc的强大之处不仅仅在于上面的功能,除此之外,我们还可以灵活的定制生成注释的规则,这将使我们能够自由的控制最后生成注释的格式等。在Visual Studio 2008的菜单项Tools->GhostDoc->Configure GhostDoc中可以打开GhostDoc配置界面,如下图:
配置界面:
对于配置项的解释如下所示:
Rules 修改,删除,添加文本生成规则
Acronyms 指定将哪些单词视为首字母缩写词
"of the"Reordering 指定触发重新排序行为的单词
"No the"Words 指定哪些词前不使用"the"
Options 配置GhostDoc的其他选项
现在我们选择Method,并单击Add按钮新建一个规则:
新建的规则我们起名为MyRule,如下图所示:
单击summary后面的按钮,我们设置其规则,如下图所示:
设置完规则之后,我们再看生成的注释:
1: /// <summary>
2: /// <remark>
3: /// * Author : TerryLee
4: /// * Date : 2008/7/2
5: /// * Machine : TERRYLEE-PC
6: /// </remark>
7: /// </summary>
8: /// <param name="item">The item.</param>
9: /// <returns></returns>
10: public bool Add(string item)
11: {
12: //......
13: }
14:
15: /// <summary>
16: /// <remark>
17: /// * Author : TerryLee
18: /// * Date : 2008/7/2
19: /// * Machine : TERRYLEE-PC
20: /// </remark>
21: /// </summary>
22: /// <param name="item">The item.</param>
23: /// <returns></returns>
24: public bool Remove(string item)
25: {
26: //......
27: }
28:
29: /// <summary>
30: /// <remark>
31: /// * Author : TerryLee
32: /// * Date : 2008/7/2
33: /// * Machine : TERRYLEE-PC
34: /// </remark>
35: /// </summary>
36: /// <param name="htmlProvider">The HTML provider.</param>
37: public void AppendHtmlText(IHtmlProvider htmlProvider)
38: {
39: //......
40: }
大家可以看到,现在的注释已经是按照我们预定规则进行生成。
总结
本文详细介绍了强大的注释生成工具GhostDoc,希望大家在开发中能够很好的使用,提高你的开发效率以及生成标准的XML注释。在后面的文章中,我将继续介绍其它的工具。
原文:
http://www.dotneteye.cn/post/2008/07/12/dotnet-develop-tools-part-2.aspx