一,准备工作
1,首先介绍一款VS的代码注释插件GhostDoc
你也许认为我们在代码中敲入///就能自动生成xml注释,但这种注释是没有说明文字的。而GhostDoc可以生成一些简单的说明文字,如果你的函数命名很规范的话,它生成的函数描述会很准确。并且它还能生成一些参数类型的附加说明。在你想生成代码注释的地方按下Ctrl+Shift+D,它就会自动帮你生成xml注释,非常方便。
下载地址:http://submain.com/products/ghostdoc.aspx
GhostDoc毕竟是个免费版,功能也有限,作为程序员有必要掌握一些常用的用于生成xml注释的标签。
可以参考园子里的这篇文章,写的很好 http://www.cnblogs.com/zhangziqiu/archive/2009/01/23/1380416.html
2,在VS中生成帮助文档的xml文件
如果是C#的工程,需要把工程的Property-->Build-->Xml Document Fiel选中,并为生成的xml文件取一个名字,
这样,我们编译的时候,就会自动生成代码注释xml文件了。需要注意一点,三个/的注释才会生成,两个/的注释是不会生成的。
3,下载帮助文档的生成工具
以前微软维护了一个叫Sandcastle的生成工具,被认为是NDoc的继承者。不过现在Sandcastle已经停止维护了,被移交到了这里
http://shfb.codeplex.com/ 由另外一个牛人进行维护,命名为Sandcastle Help File Builder,大家可以去下载这个工具。
下面我们就用最新的Sandcastle Help File Builder来制作一个简单的帮助文档。
二,制作帮助文档
1,在开始菜单中打开Sandcastle Help File Builder GUI这个软件,生成一个新工程。
2,导入我们的xml和对应的dll或exe文件
找到最右边的Project Explorer-->Documentation source,点右键,可以添加对应的带有注释的xml文件,添加xml文件的同时,会把同名的dll或exe文件一并导入。
但是我们也可以选择导入工程文件(.csproj),这样生成帮助文档的过程中,用到其他参照的dll会自动解决,省去了很多的麻烦。
我第一次用的是选dll这种方式,结果发现一些参照dll找不到,导致生成不成功,然后采用选择工程文件这种方式一切就OK了。
3,导入必要的文件后,我们还需要对要生成的chm文件做一些设置。
4,查看生成的chm文件
默认的生成文件放在了My Document下面。比如我生成的文件放在了My Document-->Help-->MyFirstHelperFile.chm位置 。
下面的图对应于上图中每个设置部分的作用效果。
到此,一个简单的chm帮助文件就做好了。这个工具还可以添加一些额外的图片,txt,html等内容一起生成更加丰富的chm文件。
由于我目前用不到这些功能,没有进一步研究