一、工具的准备
目前,一般采用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
二、 制作帮助文档
制作过程,我就不写了,要充分利用已有资源,尽量不要重复做重复的事情,网上有教程已经将其写的很明白了。
说明一些注意事项。
事项一:
如果是C#的工程,需要把工程的属性-->生成-->Xml文档文件选中。如果是其他工程的话,只要属性里面包含Xml Document Fiel,我们就勾选上。如下图:
事项二:
如果生成的chm文件内容不显示,如下图
我这里出现这种情况主要是chm文件的路径中包含有“#”特殊字符所造成的,注意当chm文件的路径中含有“#”“%”等字符时,chm文件能够打开,但将无法显示。
此方法参照:chm电子书显示“此程序无法显示网页”的完美解决办法