Javascript自动化文档工具JSDuck在Windows下的使用心得

作者： 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