JSDoc 3 生成javascript API文档

一、javascript注释规范

　　我们在编写javascript文件的时候，一般会添加一些注释。例如一些文件、类、方法和属性都应该用合适的标记和类型进行注释。这里不但方便我们的阅读，也能养成一个好的习惯。更大的好处是，我们可以根据这些注释生成帮助文档。如下就是一个比较规范的javascript注释例子。

/**
* MyClass类
* @class MyClass
* @constructor
*/
function MyClass() {

/**
* a属性
* @property a
* @type int
**/
var a = 0;

/**
获得A的值
@memberof MyClass
@method getA
@param returnType {int} 要设置的值
@example   ele.setReturnType('0000');
**/
function setA(a) {
this.a = a;
}

/**
设置A的值
@memberof MyClass
@method getA
@param returnType {int} 要设置的值
@example   ele.setReturnType('0000');
**/
function getA() {
return a;
}

}

二、JSDoc 3

　　JSDoc 3是一个生成为Javascript生成API文档的工具。下载地址为：https://github.com/jsdoc3/jsdoc 。使用JSDoc 3 我们需要有Node.js环境。Node.js安装好之后，我们可以通过如下命令，可以按照最好的alpha版本：

npm install jsdoc@"<=3.3.0"

　　在cmd输入该命令，回车。当显示如下结果的时候，说明JSDoc 3已经安装完成



　　不过此时JSDoc 3并没被添加到系统环境下。此时我们可以在cmd中进入C:\Users\user\node_modules\.bin该目录下，输入jsdoc -v，会显示安装的版本。我们将要生成文档的js文件拷贝到这个文件夹下，在cmd里面输入命令jsdoc test.js,目录下会生成out文件目录，该目录里面就是生成的API 文档。

　　文件上面的代码保存到test.js中，生成的API文档如下图所示



三、JSDoc 3相关配置了解

　　1、我们使用JSDoc生成javascriptAPI文档，必须要使用规范的注释。该注释可以参考 http://usejsdoc.org/.

　　2、为多个文件生成帮助文档

　　　　此时我们可以配置C:\Users\user\node_modules\jsdoc目录下的conf.json.EXAMPLE文件。为这个文件source里面添加一行如下图所示：



　　将要生成API文档的JS文件名称配置进入，然后将这写配置了的JS文件拷贝到C:\Users\user\node_modules\.bin这个文件夹里面。在cmd里面运行jsdoc，即可生成API文档。

　　注意：可能我们生成的API文档会有乱码，因为JSDoc 3生成的API文档默认是使用utf8编码格式生成文档。当我们的js文件内容不是使用utf8的时候，就会产生乱码。此时我们将JS文件都改成utf8编码，然后重新生成帮助文档，这样就不会有编码问题。