JSDuck用法详解

字数：3692字

阅读时间：15分钟

前言

​ 首先，咱们有一个前提，JSDuck对我们而言只是一个便于API查看的文档化工具。因此，只要它能够满足我们文档化的所有需求，并且优雅地显示出来就足够了。所以，这篇文章旨在告诉大家，在日常工作中，我们如何使用这个工具，至于里面的实现原理、编程思想或者自定义标签等咱一概不讲。

​ 如果是之前完全没有接触过JSDuck或者机器上没有JSDuck环境，建议可以先花5分钟看一下笔者的另一篇文章 五分钟玩转文档化工具JSDuck。可以先将环境搭建起来，对JSDuck也有一个可视化的认识。

​ 接下来，笔者将从基本概念、标签、工具使用三个方面，和你一起认识认识JSDuck文档化工具。

​ 提别标明一下，文章所有讲述的内容都是基于当前最新的版本JSDuck5

1.基本概念

---

​ JSDuck将代码组成分为两大部分：类和类中成员。其中，成员又分为配置、属性、函数、事件、文档样式几个部分。因此，使用JSDuck有一个基础——我们的代码都是以面向对象的方式编写的。

​ 其次，JSDuck的数据类型包括JS原始类型、JS内嵌类型和DOM类型三大类型。

​ JS原始类型：

​ boolean：布尔类型

​ number：数值类型

​ string：字符串类型

​ void：无返回值

​ undefine：未定义

​ JS内嵌类型：

​ Number：数值类型

​ String：数值类型

​ Boolean：布尔类型

​ Object：对象

​ Array：数组类型

​ Date：日期类型

​ Function：函数类型

​ Arguments：函数参数

​ Error：错误类型

​ Regex：正则对象

​ null：空值

​ DOM类型：

​ HTMLElement：html节点类型

​ XMLElement：xml节点类型

​ NodeList：DOM节点集合类型

​ TextNode：DOM文本节点类型

​ CSSStyleSheet：样式表对象

​ CSSStyleRule：样式规则对象

​ Event：DOM事件类型

​ 这些数据类型都是JSDuck默认支持的数据类型，它们都是我们在写代码文档时可以直接使用的数据类型。此外，JSDuck还支持我们自定义数据类型，不过绝大多数情况下，这些数据类型已经足够我们使用了。

2.标签

---

​ JSDuck拥有超级丰富的标签，这也正是它功能强大的体现之一。其实学习这个工具的80%的学习成本都在标签的学习上，也就是说弄清楚了这些标签，那我们基本上就掌握了这门工具了。而且，其实在我们学习这些标签时，不仅是了解他们的用法，我们更多的是学习到这些标签背后的代码规范、设计思路和编程思想。废话不多说了，咱就开始JSDuck标签的学习吧！

​ JSDuck一共有55个标签，去除废弃的和基本不用的标签，还有39个。其中，通用标签9个，类标签9个，成员标签15个，其他标签6个。现在我们需要学习的仅仅就是这不到40个标签，而且，这40个里面有一半的标签使用频率很低。所以，实质上，我们掌握20个常用标签就能满足我们绝大部分的需求了。那么，下面我们就一起来看看这些标签的用法吧！

通用标签

通用标签作用于所有代码。

@author

示例：
/**
* @class MyClass
* My neat class.
* @author John Doe 
*/

表示代码作者的标签。

@docauthor

示例：
/**
* @class MyClass
* My neat class.
* @author John Doe 
* @docauthor Tom 
*/

表示文档作者的标签，一般情况下和代码作者一致，如果不一致时，才会使用的标签。

@example

示例：
/**
*     
*    @example
*    var pMyClass = new MyClass();
*
* @class MyClass
* My neat class.
* @author John Doe 
*/

文档示例，使用 @example 标签时注意要上下都至少空一行并且空四个。这里也可使用markdown语法代替使用。

样例还有一种用法，通过命令参数 --examples 配置示例文件目录，以页面的形式查看示例。

@link

示例：
/**
* 展示非阻挡式消息框，阻挡式弹出框见{@link GM.Alert#show GM.Alert}
* @method show
* @param strMessage
*/

内部链接标签，可以链接到文档其他位置。

@static

表明类或成员为静态的标签。

@since、@experimental 、@depercated、@new

四个标签用法一样，分别表示：代码版本之后无效标签、实验性代码标签、暂用代码标签、新增代码标签。

类标签

类标签只作用于类。

@class

语法：
@class 类名

表示类的标签。

@extends

语法：
@extends 父类名

表示当前类继承于哪个类的标签。

@alias、@alternateClassName

分别表示类的别名标签、类的说明标签。

@abstract

表明抽象类的标签。

@requires

示例：
/**
* @class TestClass
* @requires TestClass3
* @requires TestClass4
*/

表明当前类依赖的类，可以有多个依赖类。

@uses

表明当前类使用了那些类，可以有多个。

@mixins

表明多态类标签，当前类中混合了其他类的成员。

@singleton

表明当前类为单例模式类。

成员标签

成员标签作用于类中的配置、属性、函数、事件。

@member

语法：
@member 类名

表明当前成员属于哪一个类，如果代码中该成员已经属于某个类，则会自动分析出来，不需要添加该标记。

@private、@protected

分别表明当前成员是私有成员和受保护成员的标签。

@hide

文档中，子类不需要展示出来的其父类的成员标签。

@inheritable

表明可被子类继承，和@static一起使用。

@removed

表明成员已经被删除标签。

@method

示例：
/**
* @method area
* 获取圆的面积
* @param {Number} r 圆的半径
* @return {Number} 面积值
*/

作用于函数，表明函数的标签。

@param

语法：
@param name
@param {Type} name
@param {Type} [name]
@param {Type} [name="default-value"]
@param {Type} name.subproperty

作用于函数，表明函数参数的标签。

@constructor

作用于函数，表明函数是类的构造函数的标签。

@cfg

作用于函数，表明构造函数参数的标签，用法同 @param。

@return

语法：
@return {Type} 返回说明
@return {Type} return.subproperty

作用于函数，表明函数返回值标签，没有返回值就不需要添加该标签。

@abstract

作用于函数，表明函数是抽象函数的标签。

@chainable

作用于函数，表明函数是链式函数的标签。如果代码中直接返回this，则工具会自动识别为链式函数。

@throws

语法
@throws 错误描述
@throws {Type} 错误描述

作用于函数，表明函数报错时抛出的异常标签，可以添加多个标签表明多个异常，错误类型默认是 object 类型。

@fires

语法：
@fires eventName

作用于函数，表明当前函数会触发哪个事件的标签。

其他标签

其他标签作用于一些特殊代码。

@event

语法：
@event name 事件描述

作用于事件，描述事件的标签。

@preventable

作用于事件，表明事件触发函数中，返回false就可以停止冒泡的标签。

@enum

语法：
@enum
@enum {Type}
@enum {Type} EnumName
@enum [EnumName=alias.*]

示例：
/** @enum */
MyEnum = {
 /** the first enum value */
 FIRST: 'foo',
 /** the second enum value */
 SECOND: 'bar'
};

表明枚举的标签。

@property

作用于类中属性，用法同 @param ，描述属性的标签。

@readonly

作用于类中属性，表明属性是只读的标签。

@aside

语法：
@aside guide 
@aside video 
@aside example 

作用于类，表明向导的标签。

3.工具使用

---

​ 上面讲述了一堆JSDuck的概念和各种标签，那都是在约束我们如何编写代码和相应的注释。那在这个基础上，我们该如何使用这个工具呢？

​ JSDuck工具使用起来其实非常简单，就是几个简单的cmd命令就可以了。如下图所示，就是JSDuck的所有命令，一页就可以显示完全，并且我们常用的命令不到10个。

​

部分命令参数如下：

参数	含义
-- 或 空	需要生成文档的文件或者目录，也可以是一个集合
--output	文档存放的目录
--config	配置文件路径
--encoding	文档编码方式
--exclude	不生成文档的目录或文件，可以是一个集合
--title	文档标题
--footer	文档标尾
--head-html	文档页面的head中需要添加的内容
--body-html	文档页面的body中需要添加的内容
--css	额外添加的样式​
--welcome	欢迎页面
--guides	向导配置
--examples	示例配置
--categories	分类配置
--images	图片路径配置
--tags	自定义标签
--examples-base-url	示例文件的基础路径
--help	查看命令帮助
--version	查看当前版本

​ 这里要注意一点，JSDuck所有的参数都需要添加两个 “-”。例如，最常用的命令就是 ：

​ jsduck "G:\test-jsduck\test.js" --output=G:\test-jsduck\doc

​ 这条命令的意思就是将文件 G:test-jsducktest.js 中的代码生成文档，然后存放到目录 G:test-jsduckdoc 下。这是最简单的一条命令，这个命令之后可以添加上面列出的任何参数。但是每次我们都去敲一堆命令行来执行工具确实有点繁琐，下面我们一起试试更便捷的方法吧！

​ JSDuck是支持使用配置文件来执行命令的，我们只需要在执行cmd的目录下创建一个名为 jsduck.json 的文件，将所有的配置都写到这个配置文件里面，然后直接执行 jsduck 命令就行了。下面我们贴出一个标准的配置文件看看：

{
    "--title": "XXX文档",
    "--welcome": "welcome.html",
    "--warnings": ["-link", "-no_doc"],
    "--seo": true,
    "--": [
        "./common/js",
        "./custom",
        "./libs/angular/custom"
    ],
    "--output": "./docs",
    "--examples-base-url": "./examples",
    "--examples": "./examples.json",
    "--body-html": [
        ""
    ],
    "--tags":["tags/my_custom_tag.rb"]
}

​ 如果想省事情，可以直接把这段配置拷贝过去，按照自己的实际环境设置一下属性，就可以直接使用了。下面，我们一起来解读一下这段配置的含义。

"--title": "XXX文档",

配置文档在浏览器中显示的标签名称和页面的标题名称为 “XXX文档”。

"--welcome": "welcome.html",

配置文档欢迎页面的路径为“welcome.html”，这里配置的是相对当前运行命令的路径。

"--warnings": ["-link", "-no_doc"],

配置生成文档时，遇到未知的连接或缺失文档的代码时，不生成警告日志。参数值里面，“-”表示

关闭警告，“+”表示打开警告，查看详细警告信息可以键入jsduck --help=warings

"--seo": true,

配置生成文档时，进行SEO优化。

"--": [
        "./common/js",
        "./custom",
        "./libs/angular/custom"
    ],

配置需要生成文档的内容，这里我配置了一个集合，里面包含了三个目录，这三个目录下所有的文件都会被扫描并生成文档。这里，我们也可以配置到具体的一个文件。

"--output": "./docs",

配置生成的文档文件的保存目录为当前目录下的 docs 文件夹。

"--examples-base-url": "./examples",

配置生成的文档中示例的基准目录为当前目录下的 examples文件夹，文档中需要使用的示例文件都以这个目录为基础路径。

"--examples": "./examples.json",

配置示例文件路径为当前目录下名为 examples.json 的文件，文件内容如下：

[
   {
       "title": "Combination Examples",
       "items": [
           {
               "name": "feed-viewer",
               "title": "Feed Viewer",
               "description": "RSS feed reader example application.",
               "url": "feed-viewer.html",
               "icon": "G:/codeWorkSpace/idea/static-resources/src/main/webapp/custom/frame/frame2/img/user.png",
               "status": "updated"
           },
           {
               "name": "web-desktop",
               "text": "Web Desktop",
               "description": "A desktop in the browser using Ext components.",
               "url": "http://www.example.com/desktop.html",
               "icon": "/../../custom/frame/frame2/img/user.png",
               "status": "updated"
           }
       ]
   }
]

其中，url如果是相对路径，就是相对 "--examples-base-url" 中配置的路径

"--body-html": [
    ""
],

配置生成的文档页面中，body内需要添加的额外内容，页面元素表现如下图所示：

这里我是配置了一个版本列表的下拉菜单，里面包含了这个文档的1.0、2.0、3.0版本的链接。

"--tags":["tags/my_custom_tag.rb"]

配置自定义标签，我们这里是配置了一个ruby代码文件路径，自定义了一种标识成员为内部成员的标签。这里就需要我们具备一点ruby的知识了，该文件代码如下：

require "jsduck/tag/boolean_tag"

class Inner < JsDuck::Tag::BooleanTag
  def initialize
    @pattern = "inner"
    @signature = {:long => "inner", :short => "in"}
    super
  end
end

这就是一个自定义一个布尔类型的简单标签的示例代码。还有许多更复杂的标签定义方式，但是好在JSDuck提供的标签已经相当丰富了，绝大多数情况下，我们是不需要自定义标签的。

​ 至此，JSDuck的基本用法就已经全部介绍完毕啦！到这里的大家也已经拥有独立使用JSDuck所需的所有知识储备了，接下来我们缺的只有实战了。下一篇文章，笔者将和大伙一起实战一把，探讨一下怎样才是使用JSDuck的正确姿势。

​ 马上回来，敬请期待哦！

​ 除了该文章以外，笔者还特制了一份思维导图，以作饭后甜点食用： 一张图之——JSDuck 。

欢迎关注我的微信公众号：