五分钟玩转文档化工具JSDuck
字数：981
阅读时间：5分钟
选型依据
在经历了数个上线的项目之后，笔者所在的团队已经沉淀了一个相对稳定版本的前端框架。因此，我们需要出具一套框架API文档，以便公司其他成员的使用和框架的后期维护。我们在对现在较主流的五个文档工具：JSDoc 3、YUIDoc、Dox、Docco、JSDuck分别作了调研和尝试，得到结论如下：
| 工具 | 优点 | 缺点 |
|---|---|---|
| JSDoc3 | 提供了完整的模板开发、事件触发等接口，使用非常灵活。 | 对代码要求比较严格，学习曲线较高。 |
| YUIDoc | 不止支持JS语言，更加抽象，如果同时使用了 Ruby/PHP/Python等语言YUI都可以使用。 | 功能更加抽象，具体实现方面考虑不全。 |
| Dox | 轻量级、高度可定制化，兼容JSDoc3语法。 | 后期会有较多问题需要自己解决。 |
| Docco | 行间注释方式，更注重实现过程的文档 | 不太适合API注释 |
| JSDuck | 代码实时修改、语法灵活、支持MarkDown语法，支持查看源码并且文档可读性较高，最主要的是上手非常快。 | 可定制化支持不足，略显臃肿。 |
我们选型的条件权重由高到低依次是：
1.较强的可读性。
2.较低的学习成本。
3.注释语义的丰富程度，是否满足我们的需求。
4.是否足够灵活。
JSDuck可读性较高，上手较快，并且使用JSDuck工具生成的extJS文档的成功有目共睹，综合考量，我们最终选择了JSDuck工具。
环境部署
由于JSDuck需要依赖ruby环境，所以环境部署分为以下三步：
1.安装ruby
2.安装devkit
3.安装JSDuck
第一步，安装ruby ：
下载地址：https://rubyinstaller.org/dow...
选择符合本机电脑的安装包下载即可。
第二步，安装devkit：
下载地址：https://rubyinstaller.org/dow...
选择符合本机电脑的安装包下载即可。注意devkit安装目录不要有中文或者特殊字符，然后在安装根目录下执行cmd命令 ruby dk.rb init。这时，我们会在当前目录下看到一个config.yml文件，编辑该文件，添加ruby目录配置。例如，笔者的ruby是安装在 F:/Ruby22-x64 目录下，就做如下图修改即可：
安装成功后，执行命令 ruby dk.rb install 命令。
第三步：安装JSDuck
执行命令 gem install jsduck 命令安装jsduck。
至此，JSDuck的环境部署已经全部完成了。
第一个文档
准备工作终于做完了，那还等什么，当然是马上开始看看我们成果如何啦！
在 G:test-jsduck目录下，创建一个test.js文件，编写如下代码：
/**
* @class 人类
* @author lsjcoder
* @docauthor lsjcoder
*/
function People(){
/**
*
* @property {String} 姓名
*/
this.name = "lsjcoder";
/**
* 吃饭
* @method
* @param food {String} 食物名称
* @return {Boolean} 是否吃过
*/
this.eat = function(food){
if(food != null){
return true;
}else{
return false;
}
}
} 然后在cmd中运行命令 jsduck "G:test-jsducktest.js" --output=G:test-jsduckdoc ，工具就自动将文档生成到目录 G:test-jsduckdoc 下，直接运行里面的 index.html 文件就可以看到如下成果图：
是不是非常简单粗暴且可读性爆表呀！笔者会在接下来的系列文章中详细介绍JSDuck的所有技术，并且最后会将笔者公司在JSDuck中前端框架的实践以案例的形式分享给大家，敬请期待哦！