使用 JSDoc 3 自动生成 JavaScript API 文档
使用 JSDoc 3 自动生成 JavaScript API 文档
软件并不只是包括可以在计算机上运行的电脑程序，与这些电脑程序相关的文档，一般也被认为是软件的一部分。简单的说软件就是程序加文档的集合体。
随着项目的升级进化，前端产生的 JavaScript 代码越来越多越复杂；同时，也有越来越多的 JavaScript 问题出现，其中 JavaScript 文档的编写和维护成为一个亟待解决的难题。
许多现代编程语言都有自己的集成化文档生成工具，像 Java 有 JavaDoc ，.NET 有 NDoc，PHP 有 PHPDoc，这些自动化文档工具可以根据代码中的注释自动生成代码文档。本文将介绍的 JSDoc 也是这样的工具。
简介
JSDoc 3 是 JsDoc Toolkit 的升级版本，JsDoc Toolkit 是一个自动化文档工具，它是发布在 Google code 上的一个开源项目，和其他语言的文档工具一样，它可以自动从 JavaScript 代码中提取注释生成格式化文档。从 2010年7月27日 开始，JsDoc Toolkit 2 已经停止开发了，因此如果要使用 JSDoc 的话，还是推荐采用 JSDoc 3。现在 JSDoc 3 代码托管在 GitHub 上，项目地址：https://github.com/jsdoc3/jsdoc
安装
JSDoc 3 在本地安装依赖于 Nodejs，因此首先需要下载 Nodejs 进行安装：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
http://nodejs.org/
http://nodejs.org/dist/v0.10.25/x64/node-v0.10.25-x64.msi
`</pre>
安装完后，使用以下命令安装 JSDoc 3 即可（**注**：必须使用超级管理员身份安装）：
<pre>`# stable
npm install jsdoc@"<=3.3.0" -g
# dev
npm install git+https://github.com/jsdoc3/jsdoc.git -g
# test
C:\Users\moodpo>jsdoc --help
JSDoc 3.3.0-alpha3 (Wed, 25 Dec 2013 17:07:35 GMT)
......
`</pre>
## 使用
JSDoc 3 生成 API 文档完全依赖于你的代码注释，因此了解 JSDoc 3 的注释规则是最重要的。首先，注释必须要以 `/**` 开头，如果使用 `/*` 将不被识别；其次，每个注释块都应该包含唯一的主标签，和零个或多个副标签。
### 1\. JSDoc 3 标签规范
<table class="table table-bordered table-striped table-condensed">
<tbody>
<tr>
<td>标签</td>
<td>描述</td>
</tr>
<tr>
<td>@abstract/@virtual</td>
<td>This member must be implemented (or overridden) by the inheritor.</td>
</tr>
<tr>
<td>@access</td>
<td>Specify the access level of this member - private, public, or protected.</td>
</tr>
<tr>
<td>@alias</td>
<td>Treat a member as if it had a different name.</td>
</tr>
<tr>
<td>@augments/@extends</td>
<td>标明一个函数继承另一个函数，如 A 继承 B 则可以在 A 的注释中加 `@augments B`</td>
</tr>
<tr>
<td>@author</td>
<td>Identify the author of an item.</td>
</tr>
<tr>
<td>@borrows</td>
<td>参考，如 A 和 B 两个函数意义相同，则可以在 B 的注释中加 `@borrows A as B`，而不需重复添加注释</td>
</tr>
<tr>
<td>@callback/@typedef</td>
<td>标明此方法是一个回调函数</td>
</tr>
<tr>
<td>@classdesc</td>
<td>对一个类的描述</td>
</tr>
<tr>
<td>@constant/@const</td>
<td>常量标识</td>
</tr>
<tr>
<td>@constructor/@class</td>
<td>标明是构造器函数，可使用 `new` 关键字实例化</td>
</tr>
<tr>
<td>@constructs</td>
<td>当使用对象字面量形式定义类时，可使用此标签标明其构造函数</td>
</tr>
<tr>
<td>@copyright</td>
<td>描述版权信息</td>
</tr>
<tr>
<td>@default</td>
<td>默认值</td>
</tr>
<tr>
<td>@deprecated</td>
<td>弃用</td>
</tr>
<tr>
<td>@desc/@description</td>
<td>如果在注释开始描述可省略此标签</td>
</tr>
<tr>
<td>@enum</td>
<td>一个类中属性的类型相同时，使用此标签标明</td>
</tr>
<tr>
<td>@event</td>
<td>标明一个可触发的事件函数，一个典型的事件是由对象定义的一组属性来表示。</td>
</tr>
<tr>
<td>@example</td>
<td>示例，代码可自动高亮</td>
</tr>
<tr>
<td>@exports</td>
<td>标识此对象将会被导出到外部调用</td>
</tr>
<tr>
<td>@external/@host</td>
<td>标识此类、命名空间或模块来自外部</td>
</tr>
<tr>
<td>@file</td>
<td>描述文件功能</td>
</tr>
<tr>
<td>@fires/@emits</td>
<td>标明当一个方法被调用时将出发一个特殊类型的事件</td>
</tr>
<tr>
<td>@global</td>
<td>全局变量标识</td>
</tr>
<tr>
<td>@ignore</td>
<td>忽略此注释块</td>
</tr>
<tr>
<td>@inner</td>
<td>标明此代码是父类的内部变量</td>
</tr>
<tr>
<td>@instance</td>
<td>标明此代码是父类的实例</td>
</tr>
<tr>
<td>@kind</td>
<td>标明代码在其文档中的类型，如Class、Modual等</td>
</tr>
<tr>
<td>@license</td>
<td>采用的开源协议版本</td>
</tr>
<tr>
<td>@link</td>
<td>内联标签，创建一个链接，如 `{@link http://github.com Github}` </td>
</tr>
<tr>
<td>@member/@var</td>
<td>记录一个基本数据类型的成员变量</td>
</tr>
<tr>
<td>@memberof</td>
<td>指定一个变量所属的父类</td>
</tr>
<tr>
<td>@method/@function/@func</td>
<td>标记一个方法或函数</td>
</tr>
<tr>
<td>@mixes</td>
<td>标记一个对象混合了另一个对象的所有成员</td>
</tr>
<tr>
<td>@mixin</td>
<td>一个 `mixin` 提供了旨在将方法添加到对象上的功能</td>
</tr>
<tr>
<td>@module</td>
<td>标明当前文件模块，在这个文件中的所有成员将被默认为属于此模块，除非另外标明</td>
</tr>
<tr>
<td>@name</td>
<td>指定一段代码的名称，强制 JSDoc 使用此名称，而不是代码里的名称</td>
</tr>
<tr>
<td>@namespace</td>
<td>指定一个变量为命名空间变量</td>
</tr>
<tr>
<td>@param</td>
<td>标记方法参数及参数类型</td>
</tr>
<tr>
<td>@private/@protected/@public</td>
<td>标明变量访问等级</td>
</tr>
<tr>
<td>@property</td>
<td>标明一个对象的属性</td>
</tr>
<tr>
<td>@readonly</td>
<td>只读</td>
</tr>
<tr>
<td>@requires</td>
<td>标明运行代码所需模块</td>
</tr>
<tr>
<td>@returns/@return</td>
<td>标明返回值、类型及描述</td>
</tr>
<tr>
<td>@see</td>
<td>链接到一个参考位置</td>
</tr>
<tr>
<td>@since</td>
<td>描述此功能来自哪一版本</td>
</tr>
<tr>
<td>@static</td>
<td>描述一个不需实例即可使用的变量</td>
</tr>
<tr>
<td>@summary</td>
<td>对描述信息的短的概述</td>
</tr>
<tr>
<td>@this</td>
<td>说明 `this` 关键字所代表的意义</td>
</tr>
<tr>
<td>@throws</td>
<td>描述方法将会出现的错误和异常</td>
</tr>
<tr>
<td>@todo</td>
<td>描述函数的功能或任务</td>
</tr>
<tr>
<td>@tutorial</td>
<td>插入一个指向向导教程的链接</td>
</tr>
<tr>
<td>@type</td>
<td>描述代码变量的类型</td>
</tr>
<tr>
<td>@version</td>
<td>版本信息</td>
</tr>
</tbody></table>
更多内容请查看[官方文档](http://usejsdoc.org/#JSDoc3_Tag_Dictionary)。
### 2\. 使用 conf.json 文件
安装完 JSDoc 3 后默认使用的配置文件为 `conf.json.EXAMPLE`，内容如下：
<pre>`{
"tags": {
"allowUnknownTags": true
},
"source": {
"includePattern": ".+\\.js(doc)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
"plugins": [],
"templates": {
"cleverLinks": false,
"monospaceLinks": false
}
}
`</pre>
我们可以定义自己的 `conf.json` 文件，使用此文件可以指定 JSDoc 输出目录、命令行操作参数、使用的插件、输出模版以及读取的文件等，以下是完整的文件内容：
<pre>`// 使用时请删除所有注释
{
"tags": {
"allowUnknownTags": true //允许输出位置标签
},
"source": { // 指定读取的源文件
"include": [], // 包含文件列表
"exclude": [], // 不包含文件列表
"includePattern": ".+\\.js(doc)?$", // 正则方式
"excludePattern": "(^|\\/|\\\\)_"
},
"plugins": [], // 启用插件列表，可在 JSDoc 目录下找到所有的插件
"templates": {
"cleverLinks": false,
"monospaceLinks": false
},
"opts": { // 命令行操作参数配置，详细内容请查看 http://usejsdoc.org/about-commandline.html
"template": "templates/default", // same as -t templates/default
"encoding": "utf8", // same as -e utf8
"destination": "./out/", // same as -d ./out/
"recurse": true, // same as -r
"tutorials": "path/to/tutorials", // same as -u path/to/tutorials, default "" (no tutorials)
"query": "value", // same as -q value, default "" (no query)
"private": true, // same as -p
"lenient": true, // same as -l
// these can also be included, though you probably wouldn't bother
// putting these in conf.json rather than the command line as they cause
// JSDoc not to produce documentation.
"version": true, // same as --version or -v
"explain": true, // same as -X
"test": true, // same as -T
"help": true, // same as --help or -h
"verbose": true, // same as --verbose, only relevant to tests.
"match": "value", // same as --match value, only relevant to tests.
"nocolor": true // same as --nocolor, only relevant to tests
}
}
本文由作者按照 CC BY 4.0 进行授权