编写并生成XML文档注释

上篇文章介绍了 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 参考文档。

参考文档：

• How to: Use the XML Documentation Features