jsdoc

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
};