利用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 文件，这就是我们最终想要得到的——帮助文档，打开看一看吧，是不是挺漂亮的。