上篇文章介绍了 XML 文档注释的标记，这次演示一个例子，然后用 C# 编译器 csc.exe 生成 XML 文档注释的文件。
首先定义一个 Hello 类，其中包含一个构造函数和两个 ToString 方法，不管是类型还是成员，都加上了XML文档注释，内容如下：
Hello
1using System;
2
3namespace Netatomy.Learning
4{
5 /**//// <summary>
6 /// 经典的 Hello 类，常用来展示和介绍一门编程语言的特性。
7 /// </summary>
8 /// <seealso cref="Object"/>
9 /// <seealso cref="System"/>
10 /// <remarks>
11 /// <list type="bullet">
12 /// <item><description>该类在此处仅用于演示如何生成文档注释。</description></item>
13 /// <item><description>该类在此处没有其他任何意义。</description></item>
14 /// <item><description>该类在未来可能会被更改。</description></item>
15 /// </list>
16 /// </remarks>
17 /// <threadsafety static="true" instance="false"/>
18 /// <example>
19 /// <para>下面的代码演示了如何创建<see cref="Hello"/>类的实例并向控制台输出 Hello 信息。</para>
20 /// <code>
21 /// using System;
22 /// using Netatomy.Learning;
23 ///
24 /// public class Program
25 /// {
26 /// public static void Main(string[] args)
27 /// {
28 /// Hello hello = new Hello();
29 /// Console.WriteLine(hello.ToString());
30 /// Console.WriteLine(hello.ToString("Bill"));
31 /// }
32 /// }
33 /// </code>
34 /// </example>
35 public class Hello
36 {
37 /**//// <summary>
38 /// 默认构造函数，初始化 Hello 类的新实例。
39 /// </summary>
40 public Hello()
41 {
42 }
43
44 /**//// <summary>
45 /// 将此实例转换为其等效的 <see cref="string"/>。
46 /// </summary>
47 /// <returns>表示此实例等效的 <see cref="string"/>。</returns>
48 /// <remarks>
49 /// <para>默认返回字符串 “Hello World!”。</para>
50 /// </remarks>
51 /// <seealso cref="Object.ToString"/>
52 /// <seealso cref="Hello.ToString(string)"/>
53 public override string ToString()
54 {
55 return "Hello World";
56 }
57
58 /**//// <summary>
59 /// 将此实例转换为其等效的 <see cref="string"/>。
60 /// </summary>
61 /// <param name="name">目标名称。</param>
62 /// <returns>表示此实例等效的 <see cref="string"/>。</returns>
63 /// <remarks>
64 /// <para>返回的是类似 “Hello Bill" 的字符串，其中 “Bill” 是传入的参数。</para>
65 /// </remarks>
66 /// <seealso cref="Hello.ToString()"/>
67 public string ToString(string name)
68 {
69 return "Hello " + name;
70 }
71 }
72} 上面的代码使用了许多XML文档注释标记，其中大部分都是微软“建议的文档注释标记”，例如，<summary>、<see>、<remarks> 等，我也遵守了标准的使用方法；也有一些非建议的标记，例如，<threadsafety>、<overloads>，这些标记都被NDoc和/或Sandcastle所支持，所以也是有用的。
下面要做的事情，就是使用编译器csc.exe生成XML文件，使用方法如下：
csc.exe /doc:Hello.xml /t:library Hello.cs
回车后，csc 除了生成程序集之外，还会生成一个 Hello.xml 文件，该文件以XML的格式存储刚才编写的文档注释。csc 还会验证一些标记，以保证引用的类型或者成员是存在的，或者是没有歧义的，否则会出现警告。
如果使用 Visual Studio 则更加简单，只需要在项目属性窗口中指定文件名就可以了，每次生成时都会自动生成文档注释文件。
最终生成的文件内容如下：
XML文档注释
1<?xml version="1.0"?>
2<doc>
3 <assembly>
4 <name>Hello</name>
5 </assembly>
6 <members>
7 <member name="T:Netatomy.Learning.Hello">
8 <summary>
9 经典的 Hello 类，常用来展示并介绍一门编程语言的特性。
10 </summary>
11 <seealso cref="T:System.Object"/>
12 <seealso cref="N:System"/>
13 <remarks>
14 <list type="bullet">
15 <item><description>该类在此处仅用于演示如何生成文档注释。</description></item>
16 <item><description>该类在此处没有其他任何意义。</description></item>
17 <item><description>该类在未来可能会被更改。</description></item>
18 </list>
19 </remarks>
20 <threadsafety static="true" instance="false"/>
21 <example>
22 <para>下面的代码演示了如何创建<see cref="T:Netatomy.Learning.Hello"/>类的实例并向控制台输出 Hello 信息。</para>
23 <code>
24 using System;
25 using Netatomy.Learning;
26
27 public class Program
28 {
29 public static void Main(string[] args)
30 {
31 Hello hello = new Hello();
32 Console.WriteLine(hello.ToString());
33 Console.WriteLine(hello.ToString("Bill"));
34 }
35 }
36 </code>
37 </example>
38 </member>
39 <member name="M:Netatomy.Learning.Hello.#ctor">
40 <summary>
41 默认构造函数，初始化 Hello 类的新实例。
42 </summary>
43 </member>
44 <member name="M:Netatomy.Learning.Hello.ToString">
45 <summary>
46 将此实例转换为其等效的 <see cref="T:System.String"/>。
47 </summary>
48 <returns>表示此实例等效的 <see cref="T:System.String"/>。</returns>
49 <remarks>
50 <para>默认返回字符串 “Hello World!”。</para>
51 </remarks>
52 <seealso cref="M:System.Object.ToString"/>
53 <seealso cref="M:Netatomy.Learning.Hello.ToString(System.String)"/>
54 </member>
55 <member name="M:Netatomy.Learning.Hello.ToString(System.String)">
56 <summary>
57 将此实例转换为其等效的 <see cref="T:System.String"/>。
58 </summary>
59 <param name="name">目标名称。</param>
60 <returns>表示此实例等效的 <see cref="T:System.String"/>。</returns>
61 <remarks>
62 <para>返回的是类似 “Hello Bill" 的字符串，其中 “Bill” 是传入的参数。</para>
63 </remarks>
64 <seealso cref="M:Netatomy.Learning.Hello.ToString"/>
65 </member>
66 </members>
67</doc>
68 我们从文件中能发现这样几个特征：
- 文档描述了程序集和成员，分别用<assembly>标记和<members>标记表示。
- 针对每个类型和成员的文档注释，都被放在了相应的<member>标记中。
- 类型和类型成员都变成了完全限定名，并且都有一个前缀，类型使用“T”作为前缀，而成员使用“M”。结果 Hello 类变成了“T:Netatomy.Learning.Helo”，Hello.ToString(string) 则变成了“M:Netatomy.Learning.Hello.ToString(System.String)”。
- 构造函数的名称变成了“#ctor”。
- 除了上面的变化之外，输入的文档注释几乎原封不动地存到了文件中。
有了文档注释文件，我们接下来就可以使用 NDoc 或者 Sandcastle 这样的工具，生成 chm 帮助文档，或者 MS Help 2 格式的帮助文档，从而为我们的项目提供一个专业的 API 参考文档。
参考文档：
