『原创』教你如何使用Sandcastle Help File Builder建立MSDN风格的代码文档

今天在公司特别研究了Sandcastle、NDoc以及Sandcastle Help File Builder（以下简称SHFB）的使用，发现还是SFHB好用，特在此写下一篇供大家参考（毕竟那个界面是英文的，呵呵），过两天后将贴出大部分属性的说明（中文）。

首先，我们去http://www.codeplex.com/SHFB这里下载这个软件，安装，都按照默认就行。

其次，为了测试，我们使用VS2008在c# winform平台下建立一个类库项目，配置如下图：

然后，往默认的Class1.cs类中添加如下代码：

 

/// <summary>
        /// 根据参数返回一个字符串，参数为1则返回Hello,为0则返回Hi
        /// </summary>
        /// <param name="i">参数</param>
        /// <returns>字符串</returns>
        /// <example>
        ///  string str=ReturnHello(1);
        /// </example>
        public string ReturnHello(int i)
        {
            switch (i)
            {
                case 1:
                    return "Hello";
                    //break;
                case 0:
                    return "Hi";
                    //break;
                default:
                    return "Please Input a int";
                    //break;
            }

        }

 

然后，设置项目属性如下图：

记住：看到“输出”一栏，要在xml文档文件前打勾，路径使用默认即可。再回来生成一下项目。OK!

退出VS，打开SHFB,看到主界面，我们新建一个Project，名字随便，然后大家可以设置如下主要信息：

FrameworkVersion：框架版本，一般选择2.0的，当然根据不同的项目选择不同版本。

HelpFileFormat：这里我们不做更改

NamespaceSummaries和ProjectSummary的内容将会出现在生成的文档头部在这里我们留空即可

CopyRightText:版权信息，例如“微软”等

HelpTitle：文档标题，比如“XXXWeb控件类库”等

HtmlHelpName：生成的文件名称，可以定义为WebCommon或者你喜欢的名字

Language:语言，最好使用简体中文

PresentationStlye:显示样式，为了习惯，我们选择vs2005，也是最流行的显示样式

OutputPath:输出路径，这个想必大家都知道了

当然，还有一些比较个性化的设置如FootText这些的，都可以你自己去研究一下，然后呢，就是最重要的一步，我们要添加需要生成文档的Dll文件吧，设置好以后，我们看到右上角有个Documentation Sources，右键单击它，选择 Add Documentation Sources.，然后把上一步生成的那个HelloWorldLib.dll和配套的那个HelloWorldLib.xml文件一起添加进来。

然后，点击那个按钮，程序就开始编译了，经过一段时间，在右下角会有个进度条，生成成功后，程序会提示你：Build completed successfully at XXXXXXX某年某月的某一天

到此，我们的任务就可以算是完成了，然后转到OutPutpath的那个文件夹下，就可以看到一个.chm文档，我的如下图，呵呵：

OK，大功告成！

这里提供了整个例子的下载（包括代码和生成的文档，呵呵）：

运行环境：VS2008+.Net 3.5+C#

点此下载