C# 代码 XML 注释规范及其 .chm 帮助文档生成

一.摘要

当我们进行程序开发时,面对一个大型项目,需要多人分工合作,每人实现一个模块。当我们需要调用他人编写的模块时,首先参考的不是源码部分,而是要去通读其代码注释部分。因此,代码注释是否规范标准,很大程度上影响着项目的开发进度。

.Net允许开发人员在源代码中插入XML注释,这在多人协作开发的时候显得特别有用。C#解析器可以把代码文件中的这些XML标记提取出来,并作进一步的处理为外部文档。在项目开发中,很多人并不乐意写繁杂的文档。但是,项目管理人员希望代码注释尽可能详细;项目规划人员希望代码设计文档尽可能详尽;测试、检查人员希望功能说明书尽可能详细等等。如果这些文档都被要求写的话,保持它们同步比进行一个战役还痛苦。

因此,最好的办法就是统一规范,通过使用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这样的文档,我们需要了解更多的注释标签。下面整理了常用的注释标签:

标签名称

说明

语法

参数

标记应当用于描述类型或类型成员。使用 添加针对某个类型说明的补充信息。

标记的文本是唯一有关 IntelliSense 中的类型的信息源,它也显示在 对象浏览器 中。

<summary>

Description

summary>

description:对象的摘要。

使用 标记添加有关类型的信息,以此补充用

指定的信息。此信息显示在对象浏览器中。

<remarks>

Description

remarks>

description:成员的说明。

标记应当用于方法声明的注释中,以描述方法的一个参数。

有关 标记的文本将显示在 IntelliSense、对象浏览器和代码注释 Web 报表中。

<paramname='name'>

description

param>

name:方法参数名。将此名称用双引号括起来 (" ")。

description:参数说明。

标记应当用于方法声明的注释,以描述返回值。

<returns>

Description

returns>

description:返回值的说明。

标记使您得以描述属性所代表的值。请注意,当在 Visual Studio .NET 开发环境中通过代码向导添加属性时,它将会为新属性添加

标记。然后,应该手动添加 标记以描述该属性所表示的值。

<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>

 

四.将注释生成XML文件

我们以读写INI文件为例子,生成dll文件和xml文件。创建一个dll类库,添加代码及其相应的xml注释。在代码中添加的注释信息,可以单独提取出来,生成XML文件。在制作最后的帮助文件的时候会使用到这些注释XML文件。默认情况下是不生成注释XML文件的。

C# 代码 XML 注释规范及其 .chm 帮助文档生成_第1张图片

如上图所示,在项目的"属性页"->"生成"中, 勾选"XML文档文件"复选框,即可在编译时生成注释XML文件。生成路径默认是和dll文件在同一个文件夹下,也可以自行修改。注意此处填写的是相对路径。

五.两种Sandcastle方法生成.chm帮助文档

SandCastle是一个微软发布的工具,它通过反射程序集中的源代码以及添加代码中的XML注释来创建MSDN形式的API文档。

首先我们前往CodePlex下载Sandcastle,地址:http://sandcastle.codeplex.com/

然后下载Sandcastle Help File Builder,地址:http://shfb.codeplex.com/,点击右边download下载即可。

方法一、Visual Studio新建documentation生成帮助文档

Sandcastle是微软官方生成帮助文档这发面的工具。

它可以配合Microsoft Visual Studio生成的dll和xml注释文件生成完整的帮助文档。结合可视化工具Sandcastle Help File Builder,简单直接,还能生成各种属性的说明。

支持Helpe1x:chm, Helper2x:Hxs, Website,HelperView等多种格式而且扩展灵活功能强大,下面我们就看一下怎样用Sandcastle生成chm文档。

新建项目documentation

C# 代码 XML 注释规范及其 .chm 帮助文档生成_第2张图片

右键Documentation Sources,添加我们刚刚生成的dll和xml文件,如下图所示:

C# 代码 XML 注释规范及其 .chm 帮助文档生成_第3张图片

双击Project Properties,对工程进行相应的设置,这里对我们需要生成的帮助文档进行属性设置。

C# 代码 XML 注释规范及其 .chm 帮助文档生成_第4张图片

C# 代码 XML 注释规范及其 .chm 帮助文档生成_第5张图片

设置完成后,右键项目名,点击生成,在项目目录的Help文件夹下就会得到我们所需要的帮助文件了。

方法二、SandcastleBuilderGUI

这里使用的是可视化工具Sandcastle Help File Builder,简单直接,不需要打开Visual Studio,使用更小巧、方便。

C# 代码 XML 注释规范及其 .chm 帮助文档生成_第6张图片

C# 代码 XML 注释规范及其 .chm 帮助文档生成_第7张图片

六.注释与帮助文档

完善注释信息的最终目的就是为了能生成和MSDN一样的帮助文档,此文档将在整个项目生命周期中被多人使用,包括:开发人员通过此文档维护程序,测试人员通过此文档了解业务逻辑,项目管理人员将此文档用作项目说明等等。

所以要了解列表中这些不常见的注释究竟有何作用,就要和最终的帮助文档关联起来。下面通过示例讲解注释标签在帮助文件中的作用。

先简单看一下帮助文件的样子。我们都看过MSDN帮助文档,使用注释XML文件生成的帮助文件后缀名是 .chm,打开后和MSDN基本一样:

C# 代码 XML 注释规范及其 .chm 帮助文档生成_第8张图片

 

总结

本文介绍了.NET注释的XML格式规范和程序的DLL文件, 及如何使用SandCastle将XML注释生成类似MSDN的帮助文档。

你可能感兴趣的:(C#)