当我们进行程序开发时,面对一个大型项目,需要多人分工合作,每人实现一个模块。当我们需要调用他人编写的模块时,首先参考的不是源码部分,而是要去通读其代码注释部分。因此,代码注释是否规范标准,很大程度上影响着项目的开发进度。
.Net允许开发人员在源代码中插入XML注释,这在多人协作开发的时候显得特别有用。C#解析器可以把代码文件中的这些XML标记提取出来,并作进一步的处理为外部文档。在项目开发中,很多人并不乐意写繁杂的文档。但是,项目管理人员希望代码注释尽可能详细;项目规划人员希望代码设计文档尽可能详尽;测试、检查人员希望功能说明书尽可能详细等等。如果这些文档都被要求写的话,保持它们同步比进行一个战役还痛苦。
因此,最好的办法就是统一规范,通过使用XML规范来对代码进行注释。这里对XML规范进行了详细的描述,并讲解了如何如何生成我们所需要的帮助文档。
在所需要注释的代码前连续按三次反斜杠键(///),则可自动生成XML标注。两条斜线表示是一个注释,编译器将忽略后面的内容。三条斜线告诉编译器,后面是XML注释,需要适当地处理。
当开发人员输入三个向前的斜线后,Microsoft Visual Studio .NET IDE 自动检查它是否在类或者类成员的定义的前面。如果是的话,Visual Studio .NET IDE 将自动插入注释标记,开发人员只需要增加些额外的标记和值。下面就是在成员函数前增加三个斜线,自动增加的注释如下:
///
/// 指定的区域是否存在
///
/// 区域名
///
public virtual bool SectionExists(string Section)
{
List<string> vStrings = new List<string>();
ReadSections(vStrings);
return vStrings.Contains(Section);
}
这里嵌入的summary,param,returns标记仅仅是Visual Studio能够识别的一部分标记,然而在智能感知IntelliSense中,并没有把c#规范中所有的标记列出来,其它部分只能通过手工插入。这些手工标记一般用在特殊场合下,对导出成外部说明文件将非常有帮助。在类型和类型成员等代码构造中处理标记。编译器将处理属于有效 XML 形式的任何标记。下列提供了用户文档中常用功能的标记。具体详细内容,可通过建议的文档注释标记(C# 编程指南)查看。
|
|
|
|
* |
|
|
|
|
|
|
|
|
|
|
|
|
|
注释的使用很简单,但是我们使用到的注释很少。这是因为大部分项目中注释的作用仅仅是给程序员自己看。如果想要生成类似MSDN这样的文档,我们需要了解更多的注释标签。下面整理了常用的注释标签:
标签名称 |
说明 |
语法 |
参数 |
|
|
<summary> Description summary> |
description:对象的摘要。 |
|
使用 |
<remarks> Description remarks> |
description:成员的说明。 |
标记应当用于方法声明的注释中,以描述方法的一个参数。 有关 标记的文本将显示在 IntelliSense、对象浏览器和代码注释 Web 报表中。 |
<paramname='name'> description param> |
name:方法参数名。将此名称用双引号括起来 (" ")。 description:参数说明。 |
|
|
|
<returns> Description returns> |
description:返回值的说明。 |
|
|
<value> property-description value> |
property-description:属性的说明 |
|
使用 |
<example> Description example> |
description: 代码示例的说明。 |
|
|
Text |
text :希望将其指示为代码的文本。 |
|
使用 |
<code> Content code> |
content:希望将其标记为代码的文本。 |
|
|
cref="member"> Description |
cref: 对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后,将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。 有关如何创建对泛型类型的 cref 引用的更多信息,请参见 description:异常的说明。 |
|
|
<seecref="member"/> |
cref: 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查给定的代码元素是否存在,并将 member 传递给输出 XML 中的元素名称。应将 member 放在双引号 (" ") 中。 |
|
|
<para>contentpara> |
content:段落文本。 |
|
提供了一种插入代码的方法。 |
<code src="src" language="lan" encoding="c"/> |
src:代码文件的位置 language:代码的计算机语言 encoding:文件的编码 |
* |
用以在文档中插入图片 |
<imgsrc="src"/> |
src:图片的位置,相对于注释所在的XML文件 |
|
用以在文档中插入文件,在页面中表现为下载链接 |
<filesrc="src"/> |
src:文件的位置,相对于注释所在的XML文件 |
|
提供一种注释本地化的方法,名称与当前线程语言不同的子节点将被忽略 |
<localize> <zh-CHS>中文zh-CHS> <en>Englishen> ... localize> |
|
我们以读写INI文件为例子,生成dll文件和xml文件。创建一个dll类库,添加代码及其相应的xml注释。在代码中添加的注释信息,可以单独提取出来,生成XML文件。在制作最后的帮助文件的时候会使用到这些注释XML文件。默认情况下是不生成注释XML文件的。
如上图所示,在项目的"属性页"->"生成"中, 勾选"XML文档文件"复选框,即可在编译时生成注释XML文件。生成路径默认是和dll文件在同一个文件夹下,也可以自行修改。注意此处填写的是相对路径。
SandCastle是一个微软发布的工具,它通过反射程序集中的源代码以及添加代码中的XML注释来创建MSDN形式的API文档。
首先我们前往CodePlex下载Sandcastle,地址:http://sandcastle.codeplex.com/
然后下载Sandcastle Help File Builder,地址:http://shfb.codeplex.com/,点击右边download下载即可。
Sandcastle是微软官方生成帮助文档这发面的工具。
它可以配合Microsoft Visual Studio生成的dll和xml注释文件生成完整的帮助文档。结合可视化工具Sandcastle Help File Builder,简单直接,还能生成各种属性的说明。
支持Helpe1x:chm, Helper2x:Hxs, Website,HelperView等多种格式而且扩展灵活功能强大,下面我们就看一下怎样用Sandcastle生成chm文档。
新建项目documentation
右键Documentation Sources,添加我们刚刚生成的dll和xml文件,如下图所示:
双击Project Properties,对工程进行相应的设置,这里对我们需要生成的帮助文档进行属性设置。
设置完成后,右键项目名,点击生成,在项目目录的Help文件夹下就会得到我们所需要的帮助文件了。
这里使用的是可视化工具Sandcastle Help File Builder,简单直接,不需要打开Visual Studio,使用更小巧、方便。
完善注释信息的最终目的就是为了能生成和MSDN一样的帮助文档,此文档将在整个项目生命周期中被多人使用,包括:开发人员通过此文档维护程序,测试人员通过此文档了解业务逻辑,项目管理人员将此文档用作项目说明等等。
所以要了解列表中这些不常见的注释究竟有何作用,就要和最终的帮助文档关联起来。下面通过示例讲解注释标签在帮助文件中的作用。
先简单看一下帮助文件的样子。我们都看过MSDN帮助文档,使用注释XML文件生成的帮助文件后缀名是 .chm,打开后和MSDN基本一样:
本文介绍了.NET注释的XML格式规范和程序的DLL文件, 及如何使用SandCastle将XML注释生成类似MSDN的帮助文档。