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>