使用grunt-jsdoc自动化生成javascirpt文档
背景
Javascript已经成为一门被人们重新认识的编程语言，由于大量JS开源框架的出现，利用Javascript开发的项目越来越多，越来越大。同时，也有越来越多Javascript开发问题暴露出来，如性能、网页加载速度等，其中，Javascript文档维护也成为了开发者亟待解决的一个难题。
许多现代编程语言都有自己的集成化文档生成工具，像Java有JavaDoc，.NET有NDoc，PHP有PHPDoc，这些自动化文档工具可以根据代码中的注释自动生成代码文档。
NOTE: 我个人使用的是LINUX，所以本文很多命令都是在LINUX下运作的。
依赖
JsDoc
实际上，JsDoc是一门用于标注Javascript源代码的语言。使用包含JsDoc定义的注解，程序员可以在Javascript注释中包含API文档。通过一系列工具进行批量处理，最终生成HTML或者Rich Text Format等格式的API文档。
目前JsDoc最新版本是3.0。
JsDoc Toolkit
JsDoc Toolkit是一个自动化文档工具，它是发布在Google code上的一个开源项目，和其他语言的文档工具一样，它可以自动从Javascript代码中提取注释生成格式化文档。
因为JsDoc Toolkit是用Java开发的，因此如果你想要使用JsDoc Toolkit，你的机器上就需要配置JAVA环境。
NOTE:从 2010.07.27 开始，JsDoc Toolkit 2已经停止开发了，因此如果要使用JsDoc的话，还是推荐采用JsDoc3。
Grunt
Grunt是一个基于Node.js的Javascript项目管理和构建自动化工具。目前的稳定版本是0.4.1。
NOTE:关于如何在LINUX下安装GRUNT，请参考我以前编写过的这篇博文：《在Linux Mint下安装Grunt》
grunt-jsdoc
grunt-jsdoc其实就是一个JsDoc Toolkit的包装，其配置最后都会传递给JsDoc Toolkit作为参数运行。
grunt-jsdoc是一个Grunt的插件。这个插件集成了JsDoc Toolkit 3，并且你能够通过配置Grunt任务来生成API文档。
NOTE:这里有一个和grunt-jsdoc很类似的grunt插件：grunt-jsdoc-plugin，实际上他们是同一个开发者开发，但是区别是grunt-jsdoc是基于JsDoc Toolkit 3而grunt-jsdoc-plugin是基于JsDoc Toolkit 2的。之前因为不知道这个区别绕了很长的一段弯路。
安装
首先检查你是否已经安装好JAVA并且配置好JAVA_HOME这个环境变量了。JsDoc Toolkit是基于JAVA编写了，运行的时候也需要使用到JAVA环境。如果没有，LINUX下可以参考这篇文章安装和配置： Ubuntu 上使用 OpenJDK 安装并运行 Tomcat
想要在项目里面支持grunt-jsdoc其实很简单。因为本身grunt就是一个基于Node.js的软件，其插件也是通过npm进行维护的，那么我们安装jsdoc其实很方便，就一行代码。
npm install grunt-jsdoc --save-dev
grunt-jsdoc的grunt任务配置
任务配置其实也是非常的简单。在我看来，其实Grunt就只支持两种任务，分别是基本的Task以及MultiTasks。这两者的区别是基本的Task的任务配置只有一个，而MultiTasks则有多个。大多数的grunt插件任务都是MultiTasks。
Task
API:
grunt.registerTask(taskName, [description, ] taskList)
使用示例：
grunt.registerTask('default', ['jshint', 'qunit', 'concat', 'uglify']);
// 注意看，每一个taskList格式是这样的：“任务名：启用的任务配置”。通过这样的形式，我们可以指定MultiTasks运行时使用的配置，否则默认情况下，MultiTasks会依次使用每个配置去执行一遍任务。
grunt.registerTask('dist', ['concat:dist', 'uglify:dist']);
MultiTasks
API:
grunt.registerMultiTask(taskName, [description, ] taskFunction)
使用示例：
// log任务有三种不同的配置
grunt.initConfig({
log: {
foo: [1, 2, 3],
bar: 'hello world',
baz: false
}
});
// 默认情况下，MultiTasks会依次使用每个配置去执行一遍任务。
grunt.registerMultiTask('log', 'Log stuff.', function() {
grunt.log.writeln(this.target + ': ' + this.data);
});
grunt-jsdoc配置
基本语法：
grunt.initConfig({
jsdoc : {
dist : {
src: ['src/*.js', 'test/*.js'],
options: {
destination: 'doc'
}
}
}
});
参数说明：
- src: 要自动生成API文档的源文件路径数组
- jsdoc: jsdoc的bin文件夹目录
- options: jsdoc单独使用的配置项
- destination： 必填，指定文档输出路径
- configure： jsdoc配置文件路径
- template： 文档模板路径
- private： 是否在文档中输出private成员，默认为true
- 更多参数：参考官方文档：Command-line arguments to JSDoc
执行任务
基本语法：
grunt taskname
当然，如果你为某一个MultiTasks任务指定一个目标配置，也是可行的。以上面的MultiTasks中提到的作为例子就是：
// 运行concat任务，同时指定使用foo作为目标配置 // 这样在运行的时候，this.data == foo grunt concat:foo
JsDoc注解
Namepaths in JSDoc 3
在使用JsDoc之前，首先要了解一个概念就是namepath。本质上讲，namepath是JSDoc注释里明确变量的实例成员，静态成员或者内部成员的机制。
namepath的基本语法示例：
MyConstructor MyConstructor#instanceMember MyConstructor.staticMember MyConstructor~innerMember
Tutorials机制
使用Tutorials机制，你可以对你的Javascript代码做出更加详细的，更加复杂的的DEMO页面。
要启用Tutorials机制，首先你要现指定一个包含tutorials页面的文件夹路径，比如：
jsdoc: {
dev : {
src: jsdoc_src,
options: {
private : false,
destination: 'dev_release/doc/',
tutorials : 'dev_release/demo'
}
}
}
然后是时候@tutorial注解，并且指定tutorial的ID。具体来说，一个tutorial的ID其实就是文件名。（ e.g. 比如textbox_index.html的tutorialID就是textbox_index ）
/**
* web.textbox
* 文本域
* @class textbox
* @memberof web
* @extends web.formelement
* @tutorial textbox_index
* @param {Object} options - 控件配置参数
* @param {Object} element - dom对象
*/
control( 'web.textbox', web.formelement, {} )
各种注解
命名空间，模块，类声明，继承
- @class
基本语法：
@class <SomeClassName>
DEMO：
/**
* 控件基类
* @class control
* @param {Object} options - 控件配置参数
* @param {Object} element - dom对象
*/
function Control( /* options,element */ ){ };
- @memberof
定义一个符号属于另外一个父符号，这个注解其实非常好用。在Javascript类型继承其实是比较复杂的事情的，因为我们可以通过编写代码生成类构造函数来实现类的定义和继承。那这个时候，类原型的属性要怎么和类型关联起来呢？就是要通过@memberof这么一个机制实现。
如果是类型的实例成员，那么你可以以这样的语法格式编写注释：@memberof ClassName.prototype或者是@memberof ClassName#。此外还有第三种方式，就是同时使用@memberof和@instance注解。我个人都是使用第三种方式编写注释。
基本语法：
@memberof <parentNamepath>
DEMO：
/**
* web.textbox
* 文本域
* @class textbox
* @memberof web
* @extends web.formelement
* @tutorial textbox_index
* @param {Object} options - 控件配置参数
* @param {Object} element - dom对象
*/
control( 'web.textbox', web.formelement, {
/**
* 表单控件值
* @public
* @instance
* @memberof web.textbox
* @member {Object} value
* @default null
* @example <caption>get</caption>
* var value = ctrl.value();
* @example <caption>set</caption>
* ctrl.value( 'your text value' );
*/
value : function( val ){ }
}）；
- @namespace
基本语法：
@namespace [[{<type>}] <SomeName>]
DEMO：
/**
* My namespace.
* @namespace
*/
var MyNamespace = {
/** documented as MyNamespace.foo */
foo: function() {},
/** documented as MyNamespace.bar */
bar: 1
};
- @module
访问修饰符
- @public
- @private
- @protected
成员，参数，返回值
- @member
- @method
- @param
- @property
- @static
- @readonly
- @instance
- @virtual
- @return
- @event
- @borrows
- @lends
其他
- @example
- @todo
- @author
- @file
- @tutorial