【原创】三把利器快速制作代码帮助文档
2011-10-26 16:59 刺客之家 阅读(3335) 评论(6) 编辑 收藏 举报1、前言
相信不少麻油都已经积累了属于自己的代码库了，不知道是否有过这样的经历：
A:听说你上次写了个通用XXX类库啊，我正好要用到，麻烦把dll发我一下。
B:好的，你等一下，我发给你。。。
。。。十分钟后
A:喂，你这个类是怎么用的啊，有没有帮助文档啊。
B:汗，没来得及做，我来和你说吧。。。
一个好用的类库，如果能配上一个好的说明文档（最好还带搜索功能），无疑是为自己和他人提供了莫大的方便，有什么想要的功能，去文档里一查，一目了然。
我最近就碰到了这个问题，甚至更为严重的是，有很多很久之前写的代码，里面实现了哪些功能，细节我已经不是很清楚了，还需要去翻看代码，非常难管理和查找。
2、准备
那么开始今天的内容，首先需要准备好三大利器啊^_^：
一、下载安装GhostDoc:http://submain.com/download/ghostdoc/
二、下载安装sandcastlehttp://sandcastle.codeplex.com/和Sandcastle Help File Builderhttp://shfb.codeplex.com/
三、安装Visual Studio（什么？这个谁没有？好吧，咱们继续往下- -||)
3、开始
下面说一下三大利器到底怎么配合用，帮我们制造出好用的帮助文档呢？
一、给代码添加XML注释
不知道大家通常是怎么写注释的，我的习惯都是直接///然后vs帮我生成XML格式的注释，而不是简单的//或者/**/。现在有了GhostDoc(大家也可以下载GhostDoc Pro,可以批量注释，更强大)，我们就可以快速的给我们的代码添加注释了。
这一步是必不可少的，否则文档就没有了数据来源了。
如果GhostDoc不会用，可以参考这个文章，总结的很详细：http://www.cnblogs.com/RockyMyx/archive/2010/04/20/Project-Route-Using-GhostDoc.html
二、整理项目文件
这一步是做什么呢？其实主要是利用VS强大的“生成后事件”功能，配置一些宏和Marco指令，把我们代码库中的dll和注释文件xml拷贝到一起，方便制作。当然，如果您的代码全写在一个项目dll里，那这一步对您来说是没什么用处啦。反正我的库是分了20多个项目，一个个去找dll很麻烦的，所以就自动让他们放到一个输出目录下：
打开项目属性：
选择“生成”面板，允许输出XML注释文档，这步很重要
下面选择“生成事件”面板，在“生成后事件”中输入指令：
copy "$(TargetDir)*.dll" "$(TargetDir)..\..\..\OutPut"
copy "$(TargetDir)*.xml" "$(TargetDir)..\..\..\OutPut"
好了，把整个类库重新生成一下，会发现在OutPut文件夹里全部是我们要的dll和Xml:
三、使用Sandcastle Help File Builder建立帮助文档项目
打开Sandcastle Help File Builder，后面的具体步骤可以参考这篇文章：http://www.cnblogs.com/RockyMyx/archive/2010/04/30/Project-Route-Using-SandcastleBuilder.html，也很详细。按照步骤一步步做，就可以成功生成帮助文档了。
4、效果
下面看一下效果：
