让Sandcastle为你的类库生成类似于MSDN的帮助文档

为你的类库生成类似于MSDN的帮助文档
.net开发人员都知道大名鼎鼎的MSDN帮助文章，对VS2008的MSDN帮助文档，微软是这么定义的：
“MSDN Library for Visual Studio 2008 是权威的开发人员文档。我们将继续为您提供有关 Visual Studio 2008 发行版本地帮助的最新信息，同时，我们还增强了帮助选项，包括联机 F1 主题、搜索、索引以及联机或脱机使用目录的能力。有关本文档库改进功能的更多信息，请单击右侧的链接或访问新增功能页面。”
下面是MSDN的截图：

有没有想过为你的程序也生成类似的文档便于别的开发阅读你提供的类库的API文档呢？早期的开发人员可能知道NDoc这个工具，这是一个类似于JavaDoc的工具，它能将程序代码中的XML注释提取出来生成帮助文档，非常方便。
什么？你不知道什么是XML注释？看下图：

XML注释可以在别人在VS中编写代码获得智能感知效果时看到，如下图：

有时候因为某些原因不能提供程序源代码，这样就不能方便查看类库中的类和对应的方法了。早期的.net开发人员可以用NDoc来生成类库的API文档，不过NDoc不支持.net 2.0了（据说是作者知道微软要推出类似的工具停止了更新的），网上虽然有一些在NDoc的基础上开发的支持.net 2.0的版本，但是在使用过程中偶尔会出现一些问题。
微软推出了一款小软件就支持这种功能，支持生成CHM格式或者Hxs格式的文档，这款软件就是Sandcastle，它可以从http://download.codeplex.com网站上下载，下载地址是：
http://sandcastle.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=13873（如果英文不好的朋友可可以在http://download.csdn.net/zhoufoxcn下载）
从网上下载这个软件之后采用默认安装之后（假设默认安装在C:/Program Files目录下），在其安装目录下的Examples/generic会看到一个名为SandcastleGui.exe的文件，这个文件就是Sandcastle的图形化用户界面。这个软件的界面很简单，如下图所示：

Sandcastle是根据程序集和对应的XML注释文档来生成帮助文档的。不过在默认情况下是不会生成程序的XML注释文档的，需要在VS中做一下配置，在要生成帮助文档的项目上点击鼠标右键然后选择查看属性，这样就会出现项目属性配置界面，再点击“生成”选项卡，如下图所示：

选择XML文档注释，这样每次编译成功时就会生成相应的XML文档注释，默认是与生成的程序集文件在同一个目录下。
运行Sandcastle，分别添加程序集和XML文档注释，如果程序集有依赖的程序也添加一下，并且填写保存文件的名称，如果没有问题的话就会生成相应的API文档了，如果有问题就会在日志窗口看到错误信息，如下图所示。

从上图窗口中可以成功生成了NS.Common.chm文档，文档路径为：c:/Program Files/Sandcastle/Examples/NS.Common/vs2005/chm/NS.Common.chm，大小为126,213 bytes。打开c:/Program Files/Sandcastle/Examples/NS.Common/vs2005/chm/文件夹，确实可以看到一个chm文件，打开这个chm文件，会看到如下效果：

看到这个界面是不是跟MSDN有些相似呢？至此，大功告成了。顺便提一下，这个软件是公开源代码的，如果有那位朋友有兴趣和时间并且English不错的话，可以将它汉化成中文的那就更好了，不过这个工具操作非常简单，即使不汉化也容易上手。
注：Sandcastle支持将多个程序集的XML文档注释生成一个chm文件的功能，可以将多个程序集和对应XML文档注释分别放在两个文件夹下，然后用AddFolder功能一次性将文件夹下的文件添加到项目中，这样就可以将多个程序集的XML注释合并生成一个CHM文档了。
周公
于2009-4-26 01:26