JSDuck 基于 Ruby 的 JavaScript API 文档生成器

Question

JSDuck 是 Senchalabs 众多开源项目中的一个，它是使用 Ruby 编写的 JavaScript API 文档生成器，富应用形态的展现方式和树节点的命名空间管理，  避免了 YUI DOC 和 jQeury API 那样沉长页面带来的繁琐。

而文档中附加的学习的范例也 能帮助初学者尽快上手，生成这样强大的 API 文档使用的是 JSDuck ，它不仅在使用和配置上非常简单，文档的 UI 和交互方式也是目前对于开发者来说是最友好的。

功能特点

• 树形类命名空间组织
• 类子父关系的层次体系展示
• 成员与事件和配置项快速索引
• 可穿插着色代码范例演示和编辑范例代码
• 类成员源码实现部分快速导航

Linux下安装 JSDuck

Linux 发行版中通常已经预安装了Ruby，但如果要使用 JSDuck 需要将 ruby 更新至 1.8 以上的版本。

Debian 或者 ubuntu 中安装方法如下：

% sudo apt-get install ruby

之后使用之后 gem 安装 JSDuck

% sudo gem install jsduck

Windows下安装JSDuck

首先在 github 上下载最新版的二进制版本，下载之后只有一个 exe 文件，此文件中已集成好了 Ruby 解释器，不需要另外独立安装，将下载后的文 件更名为 jsduck.exe，在 windows 的环境变量的 PATH 变量中添加上此文件的路径，这样在命令行下输入 jsduck 便可可以直接调用到 jsduck.exe。

• Github 地址：https://github.com/senchalabs/jsduck
• SourceForge 二进制版本：https://sourceforge.net/projects/jsduck/files/

使用JSDuck

下面用两个文件的代码范例来展示一下 jsduck 是如何生成文档的：

people.js

/**  
* # 描述  
* 这是一个People类的描述  
*  
* **使用范例**：  
*  
*     @example  
*     var p = new People({  
*      age:2,  
*      name:'name'  
*     });  
* @class People  
*/ 
 
function People(cfg){}  
People.prototype={  
    /**
    * 事件触发描述  
    * @event sleep  
    * @param {Object} ev 事件参数的描述  
    */ 
 
    /**
    * 初始化配置年龄  
    * @cfg {Number} age  
    */ 
 
    /**
    * 初始化配置名称  
    * @cfg {String} name (required)  
    */ 
 
    /**
    * 获取它的名称  
    * @return {String} 类型为字符串  
    */ 
    getName:function(){}  
};

sub.js

/**  
* # 描述  
* 这是一个Sub类的描述  
* {@img img.png  alt text}  
* @class Sub  
* @extends People  
*/ 
function Sub(cfg){}  
Sub.prototype={  
    /**
    * 事件的描述  
    * @event eat  
    * @param {Object} ev  
    * 事件参数的描述  
    */ 
 
    /**
    * 配置项目描述  
    * @cfg {Object} size 大小  
    * @cfg {Number} size.height 初始化配置高度  
    * @cfg {Number} size.width 初始化配置宽度  
    */ 
 
    /**
    * @inheritdoc People#*  
    * @type String  
    */ 
    *:'female',  
 
    /**
    * {@link People#getName getName方法}  
    * 设置它的名称  
    * @param {String} firstName 参数的描述  
    * @param {String} lastName 参数的描述  
    */ 
    setName:function(firstName ,lastName){}  
};

在 Windows 命令行中输入：

jsduck –builtin-classes sencha\senchalabs\jsfile\ –output=sencha\senchalabs\doc\ –encoding=gbk –images= sencha\senchalabs\images

命令行参数

命令中 – 开头的为命令的参数，以下是一些常用的命令

–builtin-classes：构建 javascript 语言内建类文档，如 Array 或 Object 类的使用说明。
–output：文档输出所在目录。
–encoding：编码默认为 utf-8，如果js文件中包含了中文字符设置 gbk 即可。
–welcome:为一个 html 文件的路径，文件中的内容会被解析出来放到文档的欢迎页显示。
–eg-iframe：配置一个html文件路径，这个html文件用来配置@example范例的预览方式，如需要生成非ExtJs或者sencha touch项目的话通常都需要自定义配置。
–images：如果文档中引入了图片需配置一个图片目录。
–title：自定义文档的标题
–footer：自定义文档脚注
–help：full 显示帮助文档。

另外还有一个 –config 参数用来配置文档生成的命令集合，它的值是一个 json 配置文件的路径。 创建一个 config.json 文件。

{  
    "–output":"sencha/senchalabs/doc/",  
    "–encoding":"gbk",  
    "–":["sencha/senchalabs/jsfile/"],  
    "–eg-iframe":"sencha/senchalabs/eg-iframe.html",  
    "–welcome":"sencha/senchalabs/welcome.html",  
    "–images":"sencha/senchalabs/images" 
}

在命令行中输入

jsduck –builtin-classes –config=config.json

稍加留意会发现实际上文档的生成方式完全是基于文件中注释里面的 @tag 标签的，和 jsdoc 使用的标签规范是一样的。

注释规范需以 “/**” 开头和 “*/” 结束，在 eclipse 或者 Aptana 这类支持 javaDoc 或 jsDoc 的 IDE 中键入 “/**” 按下回车键即可生成一个符合文档生标准的注释块，如果使用 SpketIDE，注释块生成的时候还能帮助开发者自动完成函数参数的命名。

以下是一些常用标签的注解：

@class：类
@deprecated：标记此方法属性或者类不赞成使用，在升级过渡的时候需兼容之前的API时特别有用。
@example：给类或者方法添加一个代码范例，jsduck不仅会给代码着色，还能给代码生成一个代码编辑器，编辑代码后可实时预览，使用@example需要四个空格的缩进。
@extends：标记一个类继承自另一个类，生成后会有一个类型继承体系陈列在文档视图的右侧。
@cfg：构造器的配置项，并在其后跟随“{className}”，再跟随参数名。
范例：@cfg {String} fieldName配置项的描述。
@return：与@cfg类似，标记一个函数成员调用过后的返回类型。
范例：@return {Number} 文字描述
@param：与@cfg类似，给一个函数成员标记其所需的参数类型和描述，如果参数类型为多种可以用“/”分割，如需要给参数进行更详细描述还能使用“[param.member]”描述符。
范例：@param {Number/String} fieldName
范例：@param {String[]} fieldName
范例： /**
* @cfg {Object} opt
* @cfg {Number} [opt.age]
* @cfg {Number} [opt.name=0]
*/
@event：标记一个事件，随后通常会跟随@param标签给事件回调函数声明参数的说明。
@inheritdoc：在其后跟随Class#member，常用在子类覆盖父类成员后，子类注释块还需继续使用父类注释的情况下使用。
@private：将成员标记成私有，虽然也有@public但如果不特殊标明即为公有。
@protected：将成员标记成受保护的。
@static:将成员标记成静态的，静态成员也会在文档中进行分类展示。
@img：在文档注释中链接一张图片，让文档变得更具可读性。
@link：在文档注释中标记某个类或类成员的锚点。

文档化你的项目不仅可以让催悲的前端们将自己写的注释变更具有价值，也可以为项目后期维护带来巨大便捷，在协同作战环境下起着至关重要的作用。