一、javascript注释规范
我们在编写javascript文件的时候，一般会添加一些注释。例如一些文件、类、方法和属性都应该用合适的标记和类型进行注释。这里不但方便我们的阅读，也能养成一个好的习惯。更大的好处是，我们可以根据这些注释生成帮助文档。如下就是一个比较规范的javascript注释例子。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37 |
/** * 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版本：
|
1 |
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编码，然后重新生成帮助文档，这样就不会有编码问题。
JSDoc 3 生成javascript API文档,布布扣,bubuko.com
原文：http://www.cnblogs.com/always-online/p/3571733.html