GhstDoc2.1.1使用手册

 

目录

GhstDoc2.1.1使用手册    1

目录    2

修改历史纪录    3

1、GhostDoc1.2.1简介    4

2、安装(for VS2005)    4

3、配置    8

2.1、初步设置    8

2.2、GhostDoc的配置    11

2.3、热键的设置    12

4、使用GhostDoc为代码生成注释    15

4、代码注释规范    20

1、GhostDoc1.2.1简介

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

2、安装(for VS2005)

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

 

GhstDoc2.1.1使用手册

 

点击"Next":

 

GhstDoc2.1.1使用手册

 

选 "I Agree" 点击"Next":

 

GhstDoc2.1.1使用手册

 

选择要安装的路径,点击"Next":

 

GhstDoc2.1.1使用手册

 

点击"Next"开始安装:

 

GhstDoc2.1.1使用手册

 

安装完成之后,出现如下图的窗口,点击"Close"完成安装:

 

GhstDoc2.1.1使用手册

 

3、配置

2.1、初步设置

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

 

GhstDoc2.1.1使用手册

 

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

 

GhstDoc2.1.1使用手册

 

如果是第一次安装GhostDoc,点击"Create";如果要载入已有的结构,点击"Import"(此处点击"Create")。出现如下窗口:

 

GhstDoc2.1.1使用手册

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

 

GhstDoc2.1.1使用手册

 

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

 

GhstDoc2.1.1使用手册

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

 

GhstDoc2.1.1使用手册

 

2.2、GhostDoc的配置

在Visual Studio2005的菜单栏中选择"工具|GhostDoc|Configure GhostDoc",弹出对话框如下图:

GhstDoc2.1.1使用手册

其中包含的属性页:

1. Rules 修改,删除,添加文本生成规则

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

3. "of the"Reordering 指定触发重新排序行为的单词

4. "No the"Words 指定哪些词前不使用"the"

5. Options 配置GhostDoc的其他选项

2.3、热键的设置

打开Visual Studio 2005的"工具|选项",如下图:

 

GhstDoc2.1.1使用手册

 

在弹出的对话框的左边框中选择"环境|键盘",如下图:

GhstDoc2.1.1使用手册

 

在右侧键盘定义区的"显示命令包含(C):"下的输入栏里输入"ghost",如下图:

 

GhstDoc2.1.1使用手册

 

在"新快捷键用于(N):"中选择"文本编辑器",并在其后的"按快捷键(P):"中按所要设置的快捷键(这里设成Ctrl+Shift+D),如下图:

GhstDoc2.1.1使用手册

 

点击"分配",再点击"确定"完成,如下图:

 

GhstDoc2.1.1使用手册

 

4、使用GhostDoc为代码生成注释

GhostDoc为Visual Studio中的代码编辑器安装了一个新的命令。在编辑文件时,只需将光标置于要添加文档的方法或属性的内部,然后使用热键(初始化时默认是Ctrl+Shift+D)或右键菜单中的"Document this"菜单项调用命令,GhostDoc就会插入一段XML格式的注释。

这里用GhostDoc自带的一个Demo代码作介绍(双击与安装文件同一目录下的GhostDoc2.1.1DemoProject.msi,安装过程与"1 安装" 一样,安装完成后就会在"开始|所有程序|Weigelt|GhostDoc for VS 2005"目录下会出现一个"Open Demo C# Project" 选项,如下图:

GhstDoc2.1.1使用手册

打开"Open Demo C# Project",如下图:

 

GhstDoc2.1.1使用手册

 

将光标置于要添加文档的方法或属性的内部(注意,必须是内部),比如要注释Demo中的FullFileName方法,需将光标置于FullFileName方法的"{……}"中或方法名上,如下图:

 

GhstDoc2.1.1使用手册

 

然后使用热键(初始化时默认是Ctrl+Shift+D,如果初始化没设,可参考下文的设置)或右键菜单中的"Document this"菜单项调用命令,GhostDoc就会插入一段XML格式的注释,如下图:

 

GhstDoc2.1.1使用手册

 

当然,在方法或属性前面键入"///"也可以达到类似的效果,如下图给JustTesting方法注释:

GhstDoc2.1.1使用手册

 

然而后者只能够创建一段空的注释构造,而GhostDoc却能生成大部分实用的注释,如下图比较:

 

GhstDoc2.1.1使用手册

 

需要注意的是:GhostDoc生成注释的质量很大程度上取决与标识符命名的质量;而且GhostDoc也不能一次性为整个代码文件生成注释,只能每次为一个成员生成注释—如此设计是因为不管怎么样都需要你去检查它生成的每一段注释。

4、代码注释规范

GhostDoc事实上并不懂英语,那为何它生成的文档却常常令人相当满意?其中的基本原理颇为简单,GhostDoc假定你的代码遵从微软类库开发人员设计规范:

1、你的代码使用Pascal或Camel命名法为由多个单词组成的标识符命名

2、你的方法名通常以动词开头

3、你在标识符中不使用缩写

如果你能够遵从这些规则(比如,使用ClearCache()而不是Clrcch()),同时使用一些自解释的标识符名称,那么GhostDoc就能派上用场了,它把标识符分割为几个单词,将它们组合来生成注释,也许并不完美,却给你一个良好文档的开始。

文本的生成使用可定制的规则和模板,除了内置的规则,还可以定义新的自定义规则来扩展或替换既有的规则(为你的自定义规则提供更高的优先级或禁用内置规则)。

上面提到过,GhostDoc并不懂英语,但它会尝试使用某种机制来提高生成注释的质量:

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

下面是应用GhostDoc的一些例子:

GhstDoc2.1.1使用手册

是不是惊人的准确啊!!!

你可能感兴趣的:(使用)