制作Net程序的帮助文档--总结

一、工具的准备

目前，一般采用Sandcastle Help File Builder工具来制作.Net程序帮助文档，该工具主要是利用Xml文档里的信息以及DLL文件来生成完整的帮助文档。在Visual Studio中，使用三个/的注释内容才会被写入XML文档里，而两个/的注释是不会被写入的。

• 建议了解一下：XML注释标签讲解

 

1、GhostDoc--VS代码注释插件

VS本身提供了自动生成XML注释的快键方式，比如在成员函数上面敲入///，VS会自动一种注释框架，但是这种注释里是不包含关于成员函数的说明文字，我们需要手动添加这些信息。有没有自动帮我们生成一些基本信息的呢？这个答案是肯定的，GhostDoc就是这么一款能帮助生成简单的说明文字的工具，它还能生成一些参数类型的附加说明。告诉你们一个好消息，GhostDoc是免费的，我们不用99就能将其带回家。

注意：GhostDoc所生成说明信息的准确率，是与我们的函数命名规范性有关，因此根据这准确率，在一定程度上也能反映出我们函数命名是否规范哦，当然我们也可以有自己的风格，不要太拘泥。

• GhostDoc的使用http://www.cnblogs.com/zpq521/archive/2011/02/21/1959389.html
• GhostDoc下载地址：http://submain.com/products/ghostdoc.aspx

 

2、Sandcastle Help File Builder --文档生成工具

主角终于上场了，Sandcastle Help File Builder 的前身是微软的Sandcastle，Sandcastle之前被认为是NDoc的继承者，由于各种原因，Sandcastle现在已经停止维护了，取而代之的是Sandcastle Help File Builder ，它是由另外一位牛人在维护。

Sandcastle是通过提取dll文件及其xml注释文件来生成完整的帮助文档，同时还支持多种生成格式(Helpe1x:chm, Helper2x:Hxs, Website,HelperView)，结合新发布的Sandcastle Help File Builder可视化工具，整个生成过程十分简单，而且SHFB工具看起来很强大，不仅能够直接配置生成文档的各个属性，而且还支持很灵活的扩展设置，为我们提供完美的.NET类库文档成为一个可能。

如果想使用Sandcastle Help File Builder工具，我们还必须安装Sandcastle、Microsoft HTML Help。

 

必备软件下载地址：

• Sandcastle：http://www.codeplex.com/Sandcastle
• Sandcastle Help File Builder：http://shfb.codeplex.com/
• Microsoft HTML Help：http://msdn.microsoft.com/en-us/library/ms669985(VS.85).aspx

 

可选

• SandcastleGUI：http://www.inchl.nl/SandcastleGUI/ （之前一直使用的另外一个Sandcastle生成工具）
• 用Sandcastle和Help Integration Wizard把文档集成到Visual Studio

 

二、 制作帮助文档

具体制作过程，我就不写了，要充分利用已有资源，尽量不要重复做重复的事情，网上有教程已经将其写的很明白了。 还是写一下大致步骤吧。

1、打开Sandcastle Help File Builder 新建项目

2、为项目添加材料

选中Documentation Sources右键选择“Add Documentation Source…”,一般选择添加工程文件（.csproj），即可。

3、设置主要的属性

一般是设置Build和Help File。

• Build主要是检查.NET框架版本，如果与开发不配套时，需要修改。
• Help File才是我们需要设置的重点，比如文档名，文档语言，版权等。

4、生成文档

当需要的属性设置完后，点击Build按钮，就会自动帮我们生成chm文档。

如果生成失败的话，最好看看Build Output中的提示信息，查找是哪些原因导致chm文档生成失败。

 

具体的详情请见：

• 制作帮助文档参考：.Net程序帮助文档制作
• Sandcastle(Sandcastle Help File Builder)C#文档生成工具-VB.NET注释文档生成器

 

说明一些注意事项。

事项一：

如果是C#的工程，需要把工程的属性-->生成-->Xml文档文件选中。如果是其他工程的话，只要属性里面包含Xml Document Fiel，我们就勾选上。如下图：

 

事项二：

如果生成的chm文件内容不显示，如下图

我这里出现这种情况主要是chm文件的路径中包含有“#”特殊字符所造成的，注意当chm文件的路径中含有“#”“%”等字符时，chm文件能够打开，但将无法显示。

此方法参照：chm电子书显示“此程序无法显示网页”的完美解决办法