使用grunt-jsdoc自动化生成javascirpt文档

时间 2019-11-08

标签使用 grunt jsdoc 自动化生成 javascirpt 文档栏目 Node.js 繁體版

原文原文链接

背景

Javascript已经成为一门被人们从新认识的编程语言，因为大量JS开源框架的出现，利用Javascript开发的项目愈来愈多，愈来愈大。同时，也有愈来愈多Javascript开发问题暴露出来，如性能、网页加载速度等，其中，Javascript文档维护也成为了开发者亟待解决的一个难题。 html

许多现代编程语言都有本身的集成化文档生成工具，像Java有JavaDoc，.NET有NDoc，PHP有PHPDoc，这些自动化文档工具能够根据代码中的注释自动生成代码文档。 node

NOTE: 我我的使用的是LINUX，因此本文不少命令都是在LINUX下运做的。 git

依赖

JsDoc

实际上，JsDoc是一门用于标注Javascript源代码的语言。使用包含JsDoc定义的注解，程序员能够在Javascript注释中包含API文档。经过一系列工具进行批量处理，最终生成HTML或者Rich Text Format等格式的API文档。程序员

目前JsDoc最新版本是3.0。 github

JsDoc Toolkit

JsDoc Toolkit是一个自动化文档工具，它是发布在Google code上的一个开源项目，和其余语言的文档工具同样，它能够自动从Javascript代码中提取注释生成格式化文档。 web

由于JsDoc Toolkit是用Java开发的，所以若是你想要使用JsDoc Toolkit，你的机器上就须要配置JAVA环境。 npm

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