通过代码XML注释与Sandcastle生成SDK文档（进阶篇）

这篇文章介绍的内容或许你已经看过，也许你没有看过，但也感兴趣，我考虑再三，决定花些时间整理一下我所知道的分享给你，希望对你有所帮助。

用到的东东不多，主要是XML注释与Sandcastle，网上有关通过代码生成SDK的文章很少，只找到极少的原创文章，大部分都是转来转去的，可是我所碰到问题却没有找到答案。

 

网上的文章介绍的只是最简单的应用而已，生成的SDK只有命名空间下的各个类、方法的说明等，样例如下图：

而我的问题是想通过代码注释的方式生成完整的帮助手册，包括版本说明、快速入门等，如下图：

 

 

在http://sandcastle.codeplex.com/的网站上找了很多资料（都TMD是英文，真是恼火），最终找到了可以解决这个问题的方法，简单的样例如下图：

 

好，且让我从头讲来。

 

XML注释

使用Sandcastle创建帮助文档，需要在源文件中插入XML注释，在 C#是"///<></>"，在VB.net中是"'''<></>"，这些注释在编译生成xml时候被抽取出来，这是用Sandcastle自动生成CHM帮助文档必不可少的来源。

需要在项目选项中开启生成XML文档

 

 

常见标记

常见的xml文档注释标记有<summary><remark><param><returns><para>等。

<summary>用于描述类型或类型成员函数，在其声明之前标注。

<remarks>用于添加有关某个 类型的补充信息，比如类图（怎样插入图像资源下面第四点再叙述）。<remarks>标注可以嵌入在<summary>中，也可 以跟在<summary>之后。嵌入在<summary>中会在命名空间页中对类的描述表中出现（图1）； 与<summary>并列则会在类的描述页出现（图2）。

<para>可以嵌入于注释内，添加第二段说明：（此处嵌入于<summary>内）

<param>标签用于方法声明的注释中，描述方法的一个参数。语法为<param name="paramname">description</param>。

<paramref>用于代码注释中的某个单词引用某个参数，使文档以某种独特方式（通常是斜体）来设置该单词的格式。语法为<paramref name="paramname"/>。

<returns>用于方法声明的注释，描述返回值。

<see>标签用于从文本内指定链接。语法为<see cref="member"/>。

<seealso>标签指示文本放在"请参见"节中。语法为<seealso cref="member"/>。cref="member"对可以通过当前编译环境进行调用的成员或字段进行引用。编译器检查给定的代码元素是否存在，并将member传递给输出XML中的元素名。

<example>指定使用方法或其它库成员的示例，常涉及<code>。

<c>将说明中的文本标记为代码。

<code>将说明中的文本多行指示为代码。language属性可以指定代码语言(c#、vb、js等)(这个language属性在MSDN上对code注释的说明中找不到，真TM烦恼！)

例如：<code language="c#">……</code>

<value>标签用于描述属性所代表的值。

 

上面几个标签例：

其它标记就不介绍了，具体可以参考建议的文档注释标记（C# 编程指南）

只介绍一个我觉得有用的标记（微软的MSDN没说，TMD找了N久才发现，一度怀疑自己的智商有问题）

<exclude>被标记的类型/成员将排除在代码文档之外，通过这个标记可以使一些公开的类或方法不在XML注释文档中出现

 

生成xml注释文档以后，接下来的事情就简单多了

安装用Sandcastle生成CHM1.x文档

需要下载的工具包括： Sandcastle、Sandcastle GUI工具，下载安装就可以了。

 

打开Sandcastle Help File Builder界面，选择需要生成文档的程序集，然后设置一些属性。我生成的SDK样例如下图：

 

 

这个Maml格式文件我还没研究透（真TMD烦人啊！）还好，在Sandcastle Styles项目下提供了一个Html文件转Maml格式的工具（爽！），可以用这个工具将转换后再编辑一下。

 

点击Build按钮，生成文档。不一会儿功夫，文档就生成好了。

我的样例如下图：

 

当然，这只是样例，要完成这个SDK，需要将代码中的注释补充全，还要将相关的附加文件也补充完整才能真正大功告成。

只要完成以上这些工作，以后底层代码调整后再出SDK就容易了（笑~）