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

一.摘要

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

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

因此，最好的办法就是统一规范，通过使用XML规范来对代码进行注释。这里对XML规范进行了详细的描述，并讲解了如何如何生成我们所需要的帮助文档。

二.XML注释概述

在所需要注释的代码前连续按三次反斜杠键(///)，则可自动生成XML标注。两条斜线表示是一个注释，编译器将忽略后面的内容。三条斜线告诉编译器，后面是XML注释，需要适当地处理。

当开发人员输入三个向前的斜线后，Microsoft Visual Studio .NET IDE 自动检查它是否在类或者类成员的定义的前面。如果是的话，Visual Studio .NET IDE 将自动插入注释标记，开发人员只需要增加些额外的标记和值。下面就是在成员函数前增加三个斜线，自动增加的注释如下:

/// <summary>

/// 指定的区域是否存在

/// </summary>

/// <param name="Section">区域名</param>

/// <returns>返回区域检测结果</returns>

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# 编程指南）查看。

<c>	<para>	<see>*
<code>	<param>*	<seealso>*
<example>	<paramref>	<summary>
<exception>*	<permission>*	<typeparam>*
<include>*	<remarks>	<typeparamref>
<list>	<returns>	<value>

三.常见注释标签列表

注释的使用很简单,但是我们使用到的注释很少。这是因为大部分项目中注释的作用仅仅是给程序员自己看。如果想要生成类似MSDN这样的文档，我们需要了解更多的注释标签。下面整理了常用的注释标签:

标签名称	说明	语法	参数
<summary>	<summary> 标记应当用于描述类型或类型成员。使用 <remarks> 添加针对某个类型说明的补充信息。 <summary> 标记的文本是唯一有关 IntelliSense 中的类型的信息源，它也显示在对象浏览器中。	<summary> Description </summary>	description:对象的摘要。
<remarks>	使用 <remarks>标记添加有关类型的信息，以此补充用 <summary> 指定的信息。此信息显示在对象浏览器中。	<remarks> Description </remarks>	description:成员的说明。
<param>	<param> 标记应当用于方法声明的注释中，以描述方法的一个参数。有关 <param> 标记的文本将显示在 IntelliSense、对象浏览器和代码注释 Web 报表中。	<paramname='name'> description </param>	name:方法参数名。将此名称用双引号括起来 (" ")。 description:参数说明。
<returns>	<returns> 标记应当用于方法声明的注释，以描述返回值。	<returns> Description </returns>	description:返回值的说明。
<value>	<value> 标记使您得以描述属性所代表的值。请注意，当在 Visual Studio .NET 开发环境中通过代码向导添加属性时，它将会为新属性添加 <summary> 标记。然后，应该手动添加 <value> 标记以描述该属性所表示的值。	<value> property-description </value>	property-description:属性的说明
<example>	使用 <example> 标记可以指定使用方法或其他库成员的示例。这通常涉及使用 <code> 标记。	<example> Description </example>	description: 代码示例的说明。
<c>	<c> 标记为您提供了一种将说明中的文本标记为代码的方法。使用 <code> 将多行指示为代码。	<c> Text </c>	text :希望将其指示为代码的文本。
<code>	使用 <code> 标记将多行指示为代码。使用<c>指示应将说明中的文本标记为代码。	<code> Content </code>	content:希望将其标记为代码的文本。
<exception>	<exception> 标记使您可以指定哪些异常可被引发。此标记可用在方法、属性、事件和索引器的定义中。	<exception cref="member"> Description </exception>	cref: 对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后，将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。有关如何创建对泛型类型的 cref 引用的更多信息，请参见 <see> description:异常的说明。
<see> <seealso>	<see> 标记使您得以从文本内指定链接。使用 <seealso> 指示文本应该放在“另请参见”节中。	<seecref="member"/>	cref: 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查给定的代码元素是否存在，并将 member 传递给输出 XML 中的元素名称。应将 member 放在双引号 (" ") 中。
<para>	<para> 标记用于诸如<summary>，<remarks> 或 <returns> 等标记内，使您得以将结构添加到文本中。	<para>content</para>	content:段落文本。
<code>*	提供了一种插入代码的方法。	<code src="src" language="lan" encoding="c"/>	src:代码文件的位置 language:代码的计算机语言 encoding:文件的编码
<img>*	用以在文档中插入图片	<imgsrc="src"/>	src:图片的位置，相对于注释所在的XML文件
<file>*	用以在文档中插入文件，在页面中表现为下载链接	<filesrc="src"/>	src:文件的位置，相对于注释所在的XML文件
<localize>*	提供一种注释本地化的方法，名称与当前线程语言不同的子节点将被忽略	<localize> <zh-CHS>中文</zh-CHS> <en>English</en> ... </localize>