jsdoc3
jsdoc3是一个JavaScript API文档生成器。通过向源代码中添加注释进行文档描述，jsdoc工具扫描源代码并生成完整的HTML文档。
为代码添加文档注释
jsdoc的目的是为JavaScript生成API文档。它假设你的文档通过如下概念进行组织：命名空间、类、方法、方法参数等。
jsdoc注释通常需要放置在需要添加文档的代码前。必须以/**开始，星号多少都会被解析器忽略：
/** this is a simplest document */
function () {
}
添加描述很简单，只需要输入需要添加到文档的描述注释。
特殊的“文档标签”可以帮助提供更多的信息，例如，如果函数是构造函数，可以通过添加标签进行标记：
/**
* Represents a book
* @constructor
*/
function Book(title, author) {
}
jsdoc3提供了大量标签提供使用，可以为注释添加所需信息。
/**
* Represents a book
* @constructor
* @param {string} title - The title of the book
* @param {string} author - The author of the book
**/
function Book(title, author) {
}
生成网站
将代码添加了规定的注释之后，可以使用jsdoc3工具根据代码生成HTML网站。
默认情况下，jsdoc使用默认模板将文档转换为HTML。可以根据需要编辑模板来完成所需功能。
./jsdoc book.js
以上命令会创建out目录并放置HTML页面。
namepath
当需要在文档中引用其他地方的变量时，必须提供一个唯一能映射到那个变量的标识符。namepath提供一种无歧义的方法引用实例成员、静态成员以及内部变量
namepath基本语法如下：
myFunction
MyConstructor
MyConstructor#instanceMember
MyConstructor.staticMember
MyConstructor~innerMember
标签库
@abstract
同义词：@virtual
@abstract标签表示必须被继承的成员
实例：父类具有抽象方法，子类实现该方法
/**
* Generic dairy product
* @constructor
*/
function DairyProduct() {}
/**
* check whether the dairy product is solid at room temperatur.
* @abstract
* @return {boolean}
*/
DairyProduct.prototype.isSolid = function () {
throw new Error('must be implemented by subclass!');
};
/**
* cool, refreshing milk
* @constructor
* @augments DairyProduct
*/
function Milk() {}
/**
* chekc whether milk is solid at room temperature.
* @return {boolean} Always returns false
*/
Milk.prototype.isSolid = function () {
return false;
};
@access
语法：@access <private|protected|public>
@access标签指定成员的访问级别。@access private等价于@private，
@access protected等价于@protected，@access public等价于@public。
私有成员不会再文档中显示，使用--private选项后可以显示。
实例：
/** @constructor */
function Thingy() {
/** @access private */
var foo = 0;
/** @access protected */
this._bar = 1;
/** @access public */
this.pez = 2;
}
// same as
/** @constructor */
function OtherThingy() {
/** @private */
var foo = 0;
/** @protected */
this._bar = 1;
/** @public */
this.pez = 2;
}
@augments
同名：@extends
语法：@augments <namepath>
表示继承关系。
示例：Duck继承自Animal
/**
* @constructor
*/
function Animal() {
/** is this animal alive? */
this.alive = true;
}
/**
* @constructor
* @augments Animal
*/
function Duck() {}
Duck.prototype = new Animal();
/** what do ducks say? */
Duck.prototype.speak = function () {
if (this.alive) {
alert('quack!');
}
};
var d = new Duck();
d.speak(); // quack!
d.alive = false;
d.speak();
@author
语法：@author <name> [<emailAddress>]
标识作者
/**
* @authro qiu_deqing <qiu_deqing@126.com>
*/
function MyClass() {}
@callback
语法：@callback <namepath>
为传递给其他函数的回调函数定义提供信息，如回调函数需要的参数以及返回值。
定义了回调函数之后可以直接在函数参数中进行引用。
如果需要把回调定义在特定类下面，可以使用内部函数namepath来进行定义。
实例：定义类专属回调
/**
* @class
*/
function Requester() {}
/**
* send a request
* @param {Requester~requestCallback} cb - The callback that
* handles the response
*/
Requester.prototype.send = function (cb) {
// code
};
/**
* This callback is displayed as part of the Requester class
* @callback Requester~requesterCallback
* @param {number} responseCode
* @param {string} responseMessage
*/
示例：一下代码定义一个全局回调
/**
* @class
*/
function Requester() {}
/**
* send a request
* @param {requestCallback} cb - The callback that
* handles the response
*/
Requester.prototype.send = function (cb) {
// code
};
/**
* This callback is display as a global callback
* @callback requestCallback
* @param {number} responseCode
* @param {string} responseMessage
*/
@class
同名：@constructor
语法：@class [<type> <name>]
表明行数是一个构造函数，定义类。
/**
* Creates a new Person
* @class
*/
function Person() {}
var p = new Person();
@constant
同名：@const
语法：@constant [<type> <name>]
用语标记常量
/**
* red color definition
* @constant
* @type {sting}
* @default
*/
var RED = 'FF0000';
/** @constant {number} */
var ONE = 1;
@copyright
语法：@copyright <some copyright text>
描述文档的版权，通常与@file一起使用
/**
* @file this is my cool script
* @copyright qiu_deqing 2001
*/
@default
同名：@defaultvalue
语法：@default [<some value>]
/**
* @constant
* @default
*/
var RED = 'f00';
/**
* @default 222
*/
var age;
@deprecated
语法：@deprecated [some text]
标记对应条目已经废弃
/**
* @deprecated since version 2.0
*/
function old() {}
@enum
语法：@enum [type]
描述静态属性结合，类似于属性集合，通常与@readonly一起使用。
/**
* Enum for tri-state values
* @readonly
* @enum {number}
*/
var triState = {
/** the true value */
TRUE: 1,
FALSE: -1,
/** @type {boolean} */
MAYBE: true
};