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”）。

其次，遇到了环境变量与相对路径问题——

  1. 因“jsduck-5.3.4.exe”是单独下载的exe，没注册环境变量。所以我们在命令提示符中使用时，只有进入到此exe的所在目录中才能使用，否则会报错找不到exe。
  2. “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，便可生成文档。不用在“命令提示符”手工敲命令了。

img_bat.png

有时会遇到 in "mkdir": Permission denied 这样的错误信息，这一般是因文件临时被安全软件锁定了所引起的。再双击bat重新生成就行。

四、生成效果

img_home.png

img_cat.png

范例代码:

/** 动物.
 */
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://www.cnblogs.com/zyl910/p/test_jsduck_on_windows.html