利用Sandcastle製作源代碼的幫助文檔1

STEP1：瞭解

在編寫代碼時，爲類型以及類型的成員添加文檔註釋是一個好的習慣。C#以及其他.NET語言的編譯器能夠將文檔註釋處理成一個XML文件，再利用一些工具（如Sandcastle和已經死去的NDoc），還能把文檔註釋製作成幫助文檔。所以，有必要學習一下文檔註釋推薦使用的標記。

理論上，可以使用任意的標記，不過在MSDN中，推薦使用以下的文檔註釋標記：

• <c>
• <code>
• <example>
• <exception>
• <include>
• <list>
• <para>
• <param>
• <paramref>
• <permission>
• <remarks>
• <returns>
• <see>
• <seealso>
• <summary>
• <typeparam>
• <typepraramref>
• <value>

有些標記比較簡單，可能已經被大家所熟悉和使用了，比如<summary>。而且如果使用了開發工具的話（如Visual Studio），還能自動生成標記以及屬性，非常方便。

除了這些標記之外，其他語言，如VB.NET，和一些文檔生成工具，如NDoc和Sandcastle等，還補充了一些標記：

• <event>
• <exclude>
• <filterpriority>
• <note>
• <overloads>
• <preliminary>
• <threadsafety>

這些補充的標記能夠幫助文檔生成工具在生成文檔的時候，提供更豐富的內容。

參考資料：

• MSDN：Recommended Tags for Documentation Comments
• XML Documentation Comments Guide

STEP2:準備

用 C# 編譯器 csc.exe 生成 XML 文檔註釋的文件。

首先定義一個 Hello 類，其中包含一個構造函數和兩個 ToString 方法，不管是類型還是成員，都加上了XML文檔註釋，內容如下：

 

using System; namespace Netatomy.Learning { /**//// <summary> /// 經典的 Hello 類，常用來展示和介紹一門編程語言的特性。 /// </summary> /// <seealso cref="Object"/> /// <seealso cref="System"/> /// <remarks> /// <list type="bullet"> /// <item><description>該類在此處僅用於演示如何生成文檔註釋。</description></item> /// <item><description>該類在此處沒有其他任何意義。</description></item> /// <item><description>該類在未來可能會被更改。</description></item> /// </list> /// </remarks> /// <threadsafety static="true" instance="false"/> /// <example> /// <para>下面的代碼演示瞭如何創建<see cref="Hello"/>類的實例並向控制檯輸出 Hello 信息。</para> /// <code> /// using System; /// using Netatomy.Learning; /// /// public class Program /// { /// public static void Main(string[] args) /// { /// Hello hello = new Hello(); /// Console.WriteLine(hello.ToString()); /// Console.WriteLine(hello.ToString("Bill")); /// } /// } /// </code> /// </example> public class Hello { /**//// <summary> /// 默認構造函數，初始化 Hello 類的新實例。 /// </summary> public Hello() { } /**//// <summary> /// 將此實例轉換爲其等效的 <see cref="string"/>。 /// </summary> /// <returns>表示此實例等效的 <see cref="string"/>。</returns> /// <remarks> /// <para>默認返回字符串 “Hello World!”。</para> /// </remarks> /// <seealso cref="Object.ToString"/> /// <seealso cref="Hello.ToString(string)"/> public override string ToString() { return "Hello World"; } /**//// <summary> /// 將此實例轉換爲其等效的 <see cref="string"/>。 /// </summary> /// <param name="name">目標名稱。</param> /// <returns>表示此實例等效的 <see cref="string"/>。</returns> /// <remarks> /// <para>返回的是類似 “Hello Bill" 的字符串，其中 “Bill” 是傳入的參數。</para> /// </remarks> /// <seealso cref="Hello.ToString()"/> public string ToString(string name) { return "Hello " + name; } } }

上面的代碼使用了許多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 version="1.0"?> <doc> <assembly> <name>Hello</name> </assembly> <members> <member name="T:Netatomy.Learning.Hello"> <summary> 經典的 Hello 類，常用來展示並介紹一門編程語言的特性。 </summary> <seealso cref="T:System.Object"/> <seealso cref="N:System"/> <remarks> <list type="bullet"> <item><description>該類在此處僅用於演示如何生成文檔註釋。</description></item> <item><description>該類在此處沒有其他任何意義。</description></item> <item><description>該類在未來可能會被更改。</description></item> </list> </remarks> <threadsafety static="true" instance="false"/> <example> <para>下面的代碼演示瞭如何創建<see cref="T:Netatomy.Learning.Hello"/>類的實例並向控制檯輸出 Hello 信息。</para> <code> using System; using Netatomy.Learning; public class Program { public static void Main(string[] args) { Hello hello = new Hello(); Console.WriteLine(hello.ToString()); Console.WriteLine(hello.ToString("Bill")); } } </code> </example> </member> <member name="M:Netatomy.Learning.Hello.#ctor"> <summary> 默認構造函數，初始化 Hello 類的新實例。 </summary> </member> <member name="M:Netatomy.Learning.Hello.ToString"> <summary> 將此實例轉換爲其等效的 <see cref="T:System.String"/>。 </summary> <returns>表示此實例等效的 <see cref="T:System.String"/>。</returns> <remarks> <para>默認返回字符串 “Hello World!”。</para> </remarks> <seealso cref="M:System.Object.ToString"/> <seealso cref="M:Netatomy.Learning.Hello.ToString(System.String)"/> </member> <member name="M:Netatomy.Learning.Hello.ToString(System.String)"> <summary> 將此實例轉換爲其等效的 <see cref="T:System.String"/>。 </summary> <param name="name">目標名稱。</param> <returns>表示此實例等效的 <see cref="T:System.String"/>。</returns> <remarks> <para>返回的是類似 “Hello Bill" 的字符串，其中 “Bill” 是傳入的參數。</para> </remarks> <seealso cref="M:Netatomy.Learning.Hello.ToString"/> </member> </members> </doc>

我們從文件中能發現這樣幾個特徵：

• 文檔描述了程序集和成員，分別用<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

 

STEP3:生成

使用 Sandcastle 生成 chm 文檔。

 Sandcastle 是一個文檔生成工具，可以用它生成 MSDN 風格的文檔，既能夠生成 chm 文檔，也能夠生成 MS Help 2.x 幫助文檔。在此之前曾流行的 NDoc，其作者已經放棄更新。

 首先到 CodePlex 下載並安裝 Sandcastle，目前最新版本是 Sandcastle January 2008 Release。安裝後 Sandcastle 會創建一個系統環境變量 DXROOT，不要刪除，因爲 Sandcastle 要用這個環境變量。注意，如果之前安裝過 Visual Studio 2005 SDK（安裝它就意味着安裝了早期版本的 Sandcastle），請刪除用戶環境變量 DXROOT，否則將影響新版本的使用。安裝完成後，可以到安裝目錄下的 Examples 文件夾中看一看，這裏有一些示例，可以用於研究 Sandcastle 的用法。

然後，準備好你的程序集和文檔註釋文件，我使用的是上篇文章中創建的 Hello.dll 和 Hello.xml。

 接着，到 Sandcastle 安裝目錄下，把 Examples/sandcastle 文件夾下的 build_sandcastle.bat 文件複製到你的文件夾下，和 Hello.dll 以及 Hello.xml 放在一起。

最後，打開命令行，進入到這個目錄，輸入：build_sandcastle.bat vs2005 Hello <回車>。後面會出現很多信息，等這個批處理程序結束後，能看到多出了許多文件和文件夾。如果中間沒有出現問題的話，進入 chm 文件夾，將會看到一個 Hello.chm 文件，這就是我們最終想要得到的——幫助文檔，打開看一看吧，是不是挺漂亮的。