五分钟玩转文档化工具JSDuck

rickchen 发布于2019-08-21 18:41 / 1889人阅读

摘要：我们在对现在较主流的五个文档工具分别作了调研和尝试，得到结论如下工具优点缺点提供了完整的模板开发事件触发等接口，使用非常灵活。至此，的环境部署已经全部完成了。

字数：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中前端框架的实践以案例的形式分享给大家，敬请期待哦！

云服务器 GPU云服务器每天5分钟玩转kubernetes 10分钟了解Jmeter性能测试工具数据图形化工具 hbase 图形化工具

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/90725.html

JSDuck用法详解

摘要：语法父类名表示当前类继承于哪个类的标签。成员标签成员标签作用于类中的配置属性函数事件。表明可被子类继承，和一起使用。示例获取圆的面积圆的半径面积值作用于函数，表明函数的标签。作用于函数，表明构造函数参数的标签，用法同。字数：3692字阅读时间：15分钟前言首先，咱们有一个前提，JSDuck对我们而言只是一个便于API查看的文档化工具。因此，只要它能够满足我们文...

xiaochao 2019-08-21 18:41 评论0 收藏0
Javascript自动化文档工具：YUI Doc, JSDoc 3, JSDuck等比较

摘要：本文比较了种较为主流的注释文档生成工具。应该说是非常适合开源项目多个作者共同维护的一个文档工具。最后我选择了作为文档生成的工具。为了支持多种语言，它仅对注释块内部的内容进行解析。最近随着写Node以及独立的CommonJS模块越来越多，我发现有一份好的文档不仅可以帮助自己在应用这些接口的时候不至于迷糊，而且对于共同开发的情况下，能够省去大量团队的交流和Debug的时间。本文比较了...

tyheist 2019-08-22 10:56 评论0 收藏0
JSDuck实战

摘要：我们先声明了类，在类的注释上添加标签表示静态类。静态类中包含一个方法，实现了一个简单的扩展功能，后面类的继承需要用到这个接口。这里需要注意，静态类中，所有的成员也都是静态的。字数：2543 阅读时间：15分钟前言上一篇文章我们讲述了JSDuck的详细用法。那么，本文笔者就以实例为基础，和大家一起，从零开始，搭建一个简单的API文档——我们的第一个API文档V0.0.1。...

kel 2019-08-21 18:41 评论0 收藏0
JSDuck 与 AngularJS 融合技巧

摘要：融合思路解决这个问题，有两种思路。给我们带来了以下新成员模块服务指令筛选器和控制器。与其他类是通过类的名称区分的，名称统一以结尾。这种处理方式是一种折中方案，如果想要更加规范优雅的话，建议使用自定义标签来解决。字数：1568 阅读时间：10分钟前言前面，我们以一个实战案例来详细说明了如何在实际开发中使用JSDuck工具。但是，并不是所有的时候，代码的封装方式都受我们控制的。...

CarterLi 2019-08-21 18:41 评论0 收藏0
【趣味连载】攻城狮上传视频与普通人上传视频：（一）生成结构化数据

摘要：背景当知道要上传的视频资料从条变成条时，我就明白，绝对不能再人工处理了。背景当知道要上传的视频资料从20条变成100条时，我就明白，绝对不能再人工处理了。他们总是想当然的认为，录入一条数据需要1分钟，那录入20条数据就是20分钟，录入100条数据，不就是100分钟吗？我有时候，真的很想问问他们，没有考虑过人是会犯错的吗？数据越多，出错的可能就越大；但是数据本身，又是不允许出现纰漏的...

mindwind 2019-06-21 16:16 评论0 收藏0