作者： zyl910
一、工具比较
为了让前端JavaScript程序更具可维护性，更利于团队开发，文档非常重要。此时便需要使用自动化文档工具了。
我对比了各种JavaScript自动化文档工具，发现JSDuck最适合我。它的优点有——
- 生成文档的易读性高，界面美观。
- 文档注释的语法简单，功能丰富，能比较随意的编写文档注释。
- 对于 构造函数、闭包、极简主义 这3种方法定义的类，均能正确识别、生成文档。
- 提供了打包好的exe，可直接在Windows下使用，不用安装 ruby 环境。且其文件小，只有3MB左右，很适合放在代码目录中。
JSDuck强力功能点如下:
- 树形类命名空间组织
- 类子父关系的层次体系展示
- 成员与事件和配置项快速索引
- 可穿插着色代码范例演示和编辑范例代码
- 类成员源码实现部分快速导航
二、下载与环境安装
JSDuck推荐的安装办法是——先装好ruby环境，然后用gem或apt-get等命令安装JSDuck。
对于Windows平台，它还提供了打包好的exe。下载下来后直接可以用，无需安装ruby环境。
JSDuck的发布地址是——
https://github.com/senchalabs/jsduck/releases
它目前的稳定版是 5.3.4，可点击上述页面中的“jsduck-5.3.4.exe”进行下载。
三、命令行与使用心得
JSDuck是一个命令行程序，故其基本用法是——通过命令行配置好参数，然后执行该命令生成文档。
为了避免每次敲命令的重复劳动，它还提供了 --config 参数，后面接一个JSON配置文件（一般为config.json）的路径。这便能使用JSON配置中的参数了。
命令行与--config方式并不是互斥的，可同时使用。你可自由的决定哪些参数放到配置文件中，哪些直接写在命令行中。
JSDuck命令行的格式为——
jsduck [options] files/dirs...
可使用 --help 参数来查看帮助。
jsduck --help
3.1 Windows 下的使用心得
首先，因为我们现在是直接使用下载的“jsduck-5.3.4.exe”。因文件名不同，所以不能像官方教程那样用“jsduck”命令，而应该用“jsduck-5.3.4.exe”（或“jsduck-5.3.4”）。
其次，遇到了环境变量与相对路径问题——
- 因“jsduck-5.3.4.exe”是单独下载的exe，没注册环境变量。所以我们在命令提示符中使用时，只有进入到此exe的所在目录中才能使用，否则会报错找不到exe。
- “jsduck-5.3.4.exe”运行时，是先在临时目录中解压后再运行的，导致其当前目录与之前的不同。导致无法使用相对目录，特别是不适合在 config.json 中使用目录。但若写成绝对路径，却又没有通用性。
这些问题可通过Windows批处理来解决。因为批处理提供 %~dp0 变量来代表当前目录，这便可以方便的指定目录了。
例如JavaScript源码在“src”子目录，准备将文档生成到doc目录时，批处理（jsduck_make.bat）可这样写——
%~dp0jsduck-5.3.4.exe --output="%~dp0doc" --images="%~dp0images" --builtin-classes --title="test_jsduck: Test JSDuck" "%~dp0src"
pause
参数说明——
| 参数 | 说明 |
|---|---|
| --output="%~dp0doc" | 设置输出目录为当前目录下的“doc”子目录 |
| --images="%~dp0images" | 设置输出目录为当前目录下的“images”子目录 |
| --builtin-classes | 建javascript语言内建类文档，如Array或Object类的使用说明。 |
| --title="test_jsduck: Test JSDuck" | 设置文档标题 |
| "%~dp0src" | 没有其他命令约束的，就是源码目录（或文件），能支持多个源码目录。这里是将当前目录下的“src”子目录作为源码目录 |
在资源管理器中双击该bat，便可生成文档。不用在“命令提示符”手工敲命令了。
有时会遇到 in "mkdir": Permission denied 这样的错误信息，这一般是因文件临时被安全软件锁定了所引起的。再双击bat重新生成就行。
四、生成效果
范例代码:
/** 动物.
*/
var Animal = {
/** 创建 动物.
*
* @return {Animal} 返回所创建的对象.
* @static
*/
createNew: function(){
var animal = {};
/** 睡觉.
*/
animal.sleep = function(){ alert("睡懒觉"); };
return animal;
}
};
/** 猫.
*
* @extends Animal
*/
var Cat = {
/** 声音.
* @static @protected
*/
sound : "喵喵喵",
/** 创建 猫.
*
* @return {Cat} 返回所创建的对象.
* @static
*/
createNew: function(){
var cat = Animal.createNew();
/** 发声.
*/
cat.makeSound = function(){ alert(Cat.sound); };
/** 修改声音.
* @param {String} x 声音.
*/
cat.changeSound = function(x){ Cat.sound = x; };
return cat;
}
};
JSDuck对于 构造函数、闭包、极简主义 这3种方法定义的类，均能正确识别、生成文档。完整的范例源码地址:
https://github.com/zyl910/test_jsduck
参考文献
- 官网: https://github.com/senchalabs/jsduck
- 官方wiki: https://github.com/senchalabs/jsduck/wiki
- yeelan0319《Javascript自动化文档工具：YUI Doc, JSDoc 3, JSDuck等比较》. https://segmentfault.com/a/1190000002579067
- mymickey《Jsduck:前端文档生成利器Jsduck介绍及安装使用》. http://lzw.me/a/jsduck-doc.html
- 阮一峰《Javascript定义类（class）的三种方法》. http://www.ruanyifeng.com/blog/2012/07/three_ways_to_define_a_javascript_class.html