五分钟玩转文档化工具JSDuck

字数：981

阅读时间：5分钟

选型依据

---

​ 在经历了数个上线的项目以后，笔者所在的团队已经沉淀了一个相对稳定版本的前端框架。所以，咱们须要出具一套框架API文档，以便公司其余成员的使用和框架的后期维护。咱们在对如今较主流的五个文档工具：JSDoc 三、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中前端框架的实践以案例的形式分享给你们，敬请期待哦！