C#中的XML注释
上篇文章提到过如何使用Sandcastle创建C#的帮助文档，这需要在源文件中插入XML注释，以“///”的形式出现。C#的“///<></>”注释在编译生成xml时候被抽取出来，是用Sandcastle自动生成CHM帮助文档必不可少的来源。
===========================================================
目录
一、常见标记 <summary>
<remarks>
<para>
<param>
<paramref>
<returns>
<see>
<seealso>
<example>
<c>
<code>
<value>
二、示例源代码
三、其它标记： <typeparam>
<typeparamref>
<list>
<item>
<term>与<description>
<exception>
<include>
四、在注释中插入图片等资源
五、其它注意事项
六、参考文档
===========================================================
一、常见标记
常见的xml文档注释标记有<summary><remark><param><returns><para>等。
<summary>用于描述类型或类型成员函数，在其声明之前标注。
<remarks>用于添加有关某个类型的补充信息，比如类图（怎样插入图像资源下面第四点再叙述）。<remarks>标注可以嵌入在<summary>中，也可以跟在<summary>之后。嵌入在<summary>中会在命名空间页中对类的描述表中出现（图1）；与<summary>并列则会在类的描述页出现（图2）。
<para>可以嵌入于注释内，添加第二段说明：（此处嵌入于<summary>内）
<param>标签用于方法声明的注释中，描述方法的一个参数。语法为<param name=”paramname”>description</param>。
<paramref>用于代码注释中的某个单词引用某个参数，使文档以某种独特方式（通常是斜体）来设置该单词的格式。语法为<paramref name=”paramname”/>。
<returns>用于方法声明的注释，描述返回值。
<see>标签用于从文本内指定链接。语法为<see cref=”member”/>。
<seealso>标签指示文本放在“请参见”节中。语法为<seealso cref=”member”/>。cref=”member”对可以通过当前编译环境进行调用的成员或字段进行引用。编译器检查给定的代码元素是否存在，并将member传递给输出XML中的元素名。
上面几个标签例：
<example>指定使用方法或其它库成员的示例，常涉及<code>。
<c>将说明中的文本标记为代码。
<code>将说明中的文本多行指示为代码。
例：
<value>标签用于描述属性所代表的值。
--------------------------------------------------------------------------------------------------------------------------------
二、示例源代码
附：以上示例使用到的源代码：
//《TestClass.cs》
using System;
using System.Collections.Generic;
using System.Text;namespace XMLTag
{
/// <summary>
/// This is a test class
/// </summary>
/// <remarks>
/// You may have some additional information about this class.<br/>
/// There's the class diagram.<br/>
/// <img src="ClassDiagram.png" />
/// </remarks>
public class TestClass
{
/// <summary>DoWork is a method in the TestClass class.
/// <para>Here's how you could make a second paragraph in a description.<br/>
/// The <paramref name="aParam"/> parameter takes a number.<br/>
/// <see cref="TestClass.aValue"/> for information about output statements.
/// </para>
/// <seealso cref="TestClass.GetZero"/>
/// </summary>
/// <param name="aParam">Used to indicate status.</param>
/// <returns>Returns none.</returns>
public static void DoWork(int aParam)
{
// System.Console.WriteLine(System.String);
} /// <summary>
/// The GetZero method.
/// </summary>
/// <returns>returns zero.</returns>
/// <example> This sample shows how to call the GetZero method.
/// <code>
/// class MyClass
/// {
/// static int Main()
/// {
/// return GetZero();
/// }
/// }
/// </code>
/// </example>
public static int GetZero()
{
return 0;
} private string _value;
/// <value>The aValue property gets/sets the _value data member.
/// </value>
public string aValue
{
get
{
return _value;
}
set
{
_value = value;
}
}
}
}The Overview：
--------------------------------------------------------------------------------------------------------------------------------
三、其它标记
<typeparam>标签用于在泛型的类型或方法声明注释中标记类型参数。语法为<typeparam name=”typename”>description</typeparam>。
<typeparamref>使文档以某种独特方式（通常是斜体）来设置单词的格式。语法为<typeparamref name=”typename”/>。
<list>创建列表。语法为<list type=”bullet” | ”number” | “table”></list>。
<item>列表中每一项都用一个<item>块描述。
<term>与<description>一般创建定义列表时，既需要指定term也需要指定description。特别地，对于表、项目符号表、编号列表，只需为description提供一个项。
例：
/// <summary>Here is an example of a bulleted list:
/// <list type="bullet">
/// <listheader>
/// <term>The Title</term>
/// <description>something</description>
/// </listheader>
/// <item>
/// <description>Item 1.</description>
/// </item>
/// <item>
/// <description>Item 2.</description>
/// </item>
/// </list>
/// </summary>
<exception>标签用于说明异常情况。语法为<exception cref=”member”>description</exception>。
<include>标签用于引用描述源代码中类型和成员的另一文件中的注释。语法为<include file=’filename’ path=’tagpath[@name=”id”]’/>。其中filename为要包含的文档的文件名，该文件名可用tagpath限定，注意filename在单引号’’中；name为注释前边的标记中的名称说明符，name具有一个id，注意id在双引号””中。
--------------------------------------------------------------------------------------------------------------------------------
四、在注释中插入图片等资源
在SandcastleGUI的说明中知道其可以在生成的文档中插入图片等资源，网搜却不得其法。于是抱着试试看的想法给SandcastleGUI的作者inchl发了求助邮件，令人感动的是inchl两个小时后就回复了邮件并且详细地附上了操作过程，在此再次感谢作者。
操作步骤：
Step 1：创建需要的图片资源并且把它们放在一个独立的文件夹中，注意不能含有子文件夹。
Step 2：在源代码中声明对该资源的引用，注意必须对文件名引用，不能包含路径。
例如：
/// <summary>
/// This class does something.
/// </summary>
/// <remarks>
/// There is a class diagram.<br/>
/// <img src="myClassImage.png" />
/// </remarks>
Step 3：设置SandcastleGUI的时候在“directory to include in documentation (optional)”选项中选择放置图片资源的文件夹。
Step 4：设置好其它参数后，执行SandcastleGUI。
示例：
--------------------------------------------------------------------------------------------------------------------------------
五、其它注意事项
1. 包含编译好的xml和dll源文件的文件夹也不能含有子文件夹。
2. 注意生成CHM文件时存放该文件的文档会先被清空。
3. 生成的CHM文档不能放在带有“#”字符的路径下，否则会出现“页面不能打开”的错误。
--------------------------------------------------------------------------------------------------------------------------------
六、参考文档：
MSDN（C#编程指南）：建议的文档注释标记
http://msdn2.microsoft.com/zh-cn/library/5ast78ax(VS.80).aspx
感谢SandcastleGUI的作者inchl
