上篇文章介紹了 XML 文檔注釋的標(biāo)記，這次演示一個例子，然后用 C# 編譯器 csc.exe 生成 XML 文檔注釋的文件。
首先定義一個 Hello 類，其中包含一個構(gòu)造函數(shù)和兩個 ToString 方法，不管是類型還是成員，都加上了XML文檔注釋，內(nèi)容如下：
Hello
1using System;
2
3namespace Netatomy.Learning
4{
5 /**//// <summary>
6 /// 經(jīng)典的 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>下面的代碼演示了如何創(chuàng)建<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 /// 默認(rèn)構(gòu)造函數(shù)，初始化 Hello 類的新實例。
39 /// </summary>
40 public Hello()
41 {
42 }
43
44 /**//// <summary>
45 /// 將此實例轉(zhuǎn)換為其等效的 <see cref="string"/>。
46 /// </summary>
47 /// <returns>表示此實例等效的 <see cref="string"/>。</returns>
48 /// <remarks>
49 /// <para>默認(rèn)返回字符串 “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 /// 將此實例轉(zhuǎn)換為其等效的 <see cref="string"/>。
60 /// </summary>
61 /// <param name="name">目標(biāo)名稱。</param>
62 /// <returns>表示此實例等效的 <see cref="string"/>。</returns>
63 /// <remarks>
64 /// <para>返回的是類似 “Hello Bill" 的字符串，其中 “Bill” 是傳入的參數(shù)。</para>
65 /// </remarks>
66 /// <seealso cref="Hello.ToString()"/>
67 public string ToString(string name)
68 {
69 return "Hello " + name;
70 }
71 }
72} 上面的代碼使用了許多XML文檔注釋標(biāo)記，其中大部分都是微軟“建議的文檔注釋標(biāo)記”，例如，<summary>、<see>、<remarks> 等，我也遵守了標(biāo)準(zhǔn)的使用方法；也有一些非建議的標(biāo)記，例如，<threadsafety>、<overloads>，這些標(biāo)記都被NDoc和/或Sandcastle所支持，所以也是有用的。
下面要做的事情，就是使用編譯器csc.exe生成XML文件，使用方法如下：
csc.exe /doc:Hello.xml /t:library Hello.cs
回車后，csc 除了生成程序集之外，還會生成一個 Hello.xml 文件，該文件以XML的格式存儲剛才編寫的文檔注釋。csc 還會驗證一些標(biāo)記，以保證引用的類型或者成員是存在的，或者是沒有歧義的，否則會出現(xiàn)警告。
如果使用 Visual Studio 則更加簡單，只需要在項目屬性窗口中指定文件名就可以了，每次生成時都會自動生成文檔注釋文件。
最終生成的文件內(nèi)容如下：
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 經(jīng)典的 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>下面的代碼演示了如何創(chuàng)建<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 默認(rèn)構(gòu)造函數(shù)，初始化 Hello 類的新實例。
42 </summary>
43 </member>
44 <member name="M:Netatomy.Learning.Hello.ToString">
45 <summary>
46 將此實例轉(zhuǎn)換為其等效的 <see cref="T:System.String"/>。
47 </summary>
48 <returns>表示此實例等效的 <see cref="T:System.String"/>。</returns>
49 <remarks>
50 <para>默認(rèn)返回字符串 “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 將此實例轉(zhuǎn)換為其等效的 <see cref="T:System.String"/>。
58 </summary>
59 <param name="name">目標(biāo)名稱。</param>
60 <returns>表示此實例等效的 <see cref="T:System.String"/>。</returns>
61 <remarks>
62 <para>返回的是類似 “Hello Bill" 的字符串，其中 “Bill” 是傳入的參數(shù)。</para>
63 </remarks>
64 <seealso cref="M:Netatomy.Learning.Hello.ToString"/>
65 </member>
66 </members>
67</doc>
68 我們從文件中能發(fā)現(xiàn)這樣幾個特征：
- 文檔描述了程序集和成員，分別用<assembly>標(biāo)記和<members>標(biāo)記表示。
- 針對每個類型和成員的文檔注釋，都被放在了相應(yīng)的<member>標(biāo)記中。
- 類型和類型成員都變成了完全限定名，并且都有一個前綴，類型使用“T”作為前綴，而成員使用“M”。結(jié)果 Hello 類變成了“T:Netatomy.Learning.Helo”，Hello.ToString(string) 則變成了“M:Netatomy.Learning.Hello.ToString(System.String)”。
- 構(gòu)造函數(shù)的名稱變成了“#ctor”。
- 除了上面的變化之外，輸入的文檔注釋幾乎原封不動地存到了文件中。
有了文檔注釋文件，我們接下來就可以使用 NDoc 或者 Sandcastle 這樣的工具，生成 chm 幫助文檔，或者 MS Help 2 格式的幫助文檔，從而為我們的項目提供一個專業(yè)的 API 參考文檔。
參考文檔：
