JSDoc Guide

@file

对文件的描述，用于文件的头部
```
/**
 * @file 
 */
```
@author <name> [<emailAddress>]

代码的作者
在姓名后面用尖括号加上邮箱会被自动转成 mailto: 的链接
```
/**
 * @author yussicahe <[email protected]> 
 */
```
@copyright <some copyright text>

与@file结合使用，说明版权相关的信息
```
/**
 * @file 示例@copyright
 * @copyright 2015 Tencent AlloyTeam
 */
```

@license <identifier>

说明许可证相关的信息

/**
 * @file 示例@license
 * @license http://www.AlloyTeam.com/license.txt
 */

@type {typeName}

'*'表示任何类型

'?'表示可以为null

'!'表示不能为null

数组用'[]'表示

类型有多种情况需用'|'进行分隔，并加上'()'

可以使用 @callback 或 @typedef 定义的类型

/**
 * @type {number}
 */
var foo1;

/**
 * @type {*}
 * @desc 任何类型
 */
var foo2;

/**
 * @type {?string}
 * @desc string或者null
 */
var foo3;

/**
 * @type {!string}
 * @desc string且不能为null
 */
var foo4;

/**
 * @type {boolean[]}
 * @desc boelean数组
 */
var foo5;

/**
 * @type {(number|string)}
 * @desc number或者string
 */
var foo6;

/**
 * @type {object}
 * @desc 对象
 * @property {string} a - 属性a
 */
var foo7 = {
    a: 'a'
};

@var [<type>] [<name>]

标识一个变量
```
/**
 * @var
 */
var foo;
```

@property [<type>] [<name>] [some description]

描述对象的属性

/**
 * @var {object}
 * @property {string} a - 属性a
 * @property {string} b - 属性b
 */
var foo = {
    a: 'a',
    b: 'b'
}

@func [<FunctionName>]

标识一个函数

/**
 * @func
 */
function foo() {
    ...
}

@param {<type>} name - some description

非必传参数需给参数名加上'[]'

参数如有默认值需用'='表示

如果参数是object，可继续用 @param 对其属性进行详细说明

若干个参数用'...'表示

/**
 * @func
 * @desc 一个带参数的函数
 * @param {string} a - 参数a
 * @param {number} b=1 - 参数b默认值为1
 * @param {string} c=1 - 参数c有两种支持的取值</br>1—表示x</br>2—表示xx
 * @param {object} d - 参数d为一个对象
 * @param {string} d.e - 参数d的e属性
 * @param {string} d.f - 参数d的f属性
 * @param {object[]} g - 参数g为一个对象数组
 * @param {string} g.h - 参数g数组中一项的h属性
 * @param {string} g.i - 参数g数组中一项的i属性
 * @param {string} [j] - 参数j是一个可选参数 
 */
function foo(a, b, c, d, g, j) {}

/**
 * @func
 * @desc 一个带若干参数的函数
 * @param {...string} a - 参数a
 */
function bar(a) {}

@returns {<type>} some description

描述一个函数的返回值

/**
 * @func
 * @returns {boolean} 返回值为true
 */
function foo() {
    return true;
}

@namespace [{<type>}] <SomeName>]

标识一个命名空间
```
/**
 * @namespace
 */
var $ = {
    ...    
}
```
@desc <some description>

对某个部分的详细描述和说明
```
/**
 * @desc 这是一个变量
 */
var foo;
```
@summary <some description>

对某个部分的简短描述和说明
```
/**
 * @summary 一个变量
 */
var foo;
```

@constant [<type> <name>]

标识常量

/**
 * @constant {string}
 */
var COLOR_WHITE = '#fff';

@readonly

仅仅是注释，JSDoc不会去检查究竟是不是readonly
```
/**
 * @constant {string}
 * @readonly
 */
var COLOR_RED = '#f00';
```

@default [<some value>]

变量的初始值

/**
 * @constant {string}
 * @default #000
 */
var COLOR_BLACK = '#000';

@enum [<type>]

相同类型的集合

注：
默认集合中的所有项都是相同类型，可以用@type指明某一项为其他类型

/**
 * @enum {number}
 * @desc cgi常见的返回码
 */
var RETCODE = {
    /**
     * @desc 未登录
     */
    NOT_LOGIN: 100000,
    /**
     * @desc 参数错误
     */
    PARAM_ERROR: 100001,
    /**
     * @type {string}
     * @desc 未知错误
     */
    UNKOWN_ERROR: 'unkown'
}

@example

使用示例

示例代码在文档中会被高亮显示

/**
 * @func
 * @desc 计算两个数值的和
 * @param {number} a - 加数a
 * @param {number} b - 加数b
 * @returns {number} 返回a和b的和
 * @example
 * add(1, 2);    // 返回3
 */
function add(a, b) {
    return a + b;
}

@throws [{<type>} free-form description]

表明这部分代码会抛出某个异常

/**
* @func
* @throws {string} - 抛出'Error'异常
*/
function foo() {
    ...
    throw 'Error';
}

@todo text describing thing to do

后续需要做的事

 /**
  * @func
  * @todo 这个函数需要优化
  */
function foo() {
    ...
}

@deprecated [<some text>]

已弃用的标识

/**
* @func
* @deprecated 已弃用
*/
function deprecatedFunc() {
    ...
}

@borrows <that namepath> as <this namepath>

可理解为复制注释

当有多个地方引用了同一个函数，只需在一处写好注释，然后用@borrows即可

/**
 * @func
 * @param {string} a - 参数a
 * @returns {boolean} 返回值 
 */
function foo(a) {
    ...
    return true;
}

/**
 * @namespace
 * @borrows foo as bar
 */
window.$ = {
    bar: foo
}

@callback <namepath>

定义一个回调函数，和 @typedef 一样，是一种自定义类型

/**
 * @callback myCallback
 * @desc 这是自定义的type
 * @param {number} a - 参数a
 * @returns {boolean} 返回值
 */
function myCallback(a) {
    ...
    return true;
}

/**
 * @func
 * @param {myCallback} a - 参数a是一个回调函数
 */
function foo(a) {
    ...
}

@typedef [<type>] <namepath>

定义一个自定义类型

定义后可以在 @type @param 等标签中使用

/**
 * @typedef myType
 * @desc 这是自定义的type
 * @property {number} a - 属性a
 * @property {string} b - 属性b
 */

/**
 * @type myType
 */
var foo;

@this

说明此处 this 所指代的内容

/**
 *@class
 */
function myClass() {
    ...
}

/**
 * @func
 * @this myClass
 * @param {string} a - 参数a
 */
function foo(a) {
    this.a = a;
}

foo.call(new myClass(), 'a');

@global

全局标识

/**
 * @type {number}
 * @global 
 */
var foo;

@inner

内部属性或方法的标识，使用后可以通过 Parent~Child 的方式来引用

/**
 * @class 
 */
function myClass() {
    ...

    /**
     * @func
     * @inner
     */
    function foo() {
        ...
    }
}

@ignore

告诉JSDoc忽略这部分代码
```
/**
 * @ignore
 */
var foo;
```

@version

版本号

/**
 * @func
 * @version 1.0
 */
 function foo() {
    ...
}

@since

表明该内容出现在一个特定的版本之后

/**
 * @func
 * @since 2.0
 */
 function bar() {
    ...
}

@class [<type> <name>]

标识一个函数为构造函数，可以用 new 的方式实例化
```
/**
 * @class 
 */
function myClass() {
    ...
}
```

@classdesc <some description>

与 @class 结合使用

注：
与 @desc 不同，@classdesc 是对类的描述，而 @desc 是对类的构造函数的描述

/**
 * @class
 * @classdesc 这是对myClass类的描述
 * @desc 这是对myClass类的构造函数的描述
 */
function myClass() {
    ...
}

@member [<type>] [<name>]

标识类的属性

/**
 * @class
 */
function myClass() {
    ...
    /**
     * @member {string}
     */
    this.foo = 'a';
}

@method [<FunctionName>]

标识类的方法

/**
 * @class
 */
function myClass() {
    ...
}

/**
 * @method
 * @param {string} a - 参数a
 */
myClass.prototype.foo = function(a) {
    ...
}

@public

标识类的属性或方法的访问范围是public

/**
 * @class
 */
function myClass() {
    ...
}

/**
 * @method
 * @public
 * @param {string} a - 参数a
 */
myClass.prototype.foo = function(a) {
    ...
}

@private

标识类的属性或方法的访问范围是private

/**
 * @class
 */
function myClass() {
    ...
}

/**
 * @method
 * @private
 * @param {string} a - 参数a
 */
myClass.prototype.foo = function(a) {
    ...
}

@protected

标识类的属性或方法的访问范围是protected

/**
 * @class
 */
function myClass() {
    ...
}

/**
 * @method
 * @protected
 * @param {string} a - 参数a
 */
myClass.prototype.foo = function(a) {
    ...
}

@instance

实例属性或方法的标识

/**
 * @class
 */
function myClass() {
    ...
    /**
     * @member {string}
     * @instance
     */
    this.foo = 'a';
}

@static

静态属性或方法的标识

/**
 * @class
 */
function myClass() {
    ...
}

/**
 * @static
 */
myClass.foo = 'a';

@constructs <name>

当使用对象直接量去定义类时，可以通过 @constructs 标识某个函数为类的构造函数

注：
不要和 @class同时使用,否则会在文档中出现两个同名的类

createClass('myClass',
    {
        /**
         * @constructs
         * @param {string} a - 参数a
         */
        init: function (a) {
            /**
             * @member {string}
             */
            this.a = a;
        }
    }
)

@lends <namepath>

把对象直接量的属性和方法指定为某个类的属性和方法

createClass('myClass',
    /** 
     * @lends myClass.prototype
     */
    {
        /**
         * @method
         * @param {string} b - 参数b
         */
        a: function (b) {
            ...
        },
        /**
         * @method
         * @returns {boolean} 返回值
         */
        c: function () {
            return true;
        }
    }
);

@extends <namepath>

用来表明继承关系

/**
 * @class
 */
function myClass() {
    ...
}

/**
 * @class
 * @extends myClass
 */
function subClass() {
    ...
}

@abstract

标识子类必须实现或重写父类的此方法

/**
/**
 * @class
 */
function myClass() {
    ...
}

/**
 * @abstract
 * @method
 * @desc 子类需要重写这个方法
 */
myClass.prototype.foo = function () {
    ...
}

@override

表明此方法是重写了父类的同名方法

/**
 * @class
 */
function myClass() {
    ...
}

/**
 * @method
 * @param {string} a - 参数a
 * @returns {boolean} 返回值
 */
myClass.prototype.foo = function (a) {
    ...
    return true;
}

/**
 * @class
 * @extends myClass
 */
function subClass() {
    ...
}

subClass.prototype = Object.create(myClass.prototype);

/**
 * @override
 */
subClass.prototype.foo = function (a) {
    ...
    return true;
};

@interface [<name>]

定义接口

/**
 * @interface
 */
var myInterface = {
    /**
     * @method
     * @param {string} b - 参数b
     */
    a: function (b) {
        ...
    }
}

@implements {typeExpression}

实现了某个接口

/**
 * @interface
 */
var myInterface = {
    /**
     * @method
     * @param {string} b - 参数b
     */
    a: function (b) {
        ...
    }
}

/**
 * @class
 * @implements {myInterface}
 */
function myClass() {
    ...
}

myClass.prototype.a = function (b) {
    ...
}

@module [[{<type>}] <moduleName>]

定义一个模块

define(function() {
    /**
     * @module foo
     */
    var exports = {};

    /**
     * @method
     * @returns {string} 返回值
     */
    exports.a = function() {
        return 'a';
    };

    return exports;
});

@exports <moduleName>

当不是用 exports 或者 module.exports 对外提供模块接口时，需要使用 @exports 而不是 @module

define(function() {
    /**
     * @exports bar
     */
    var a = {};

    /**
     * @method
     * @param {string} c - 参数c
     */
    a.b = function (c) {
        ...
    };

    return a;
});

@requires <someModuleName>

需要某个模块

/**
 * @file 示例@requires
 * @requires module1
 * @requires module2
 */

require([
    './module1',
    './module2'
], function (module1, module2) {
    ...
});

@alias <aliasNamepath>

告诉JSDoc在生成文档时用另一个namepath去处理当前的内容

注：
@alias 不同于 @name，@name会告诉JSDoc忽略这部分代码
```
/**
 * @namespace
 */
var $ = {};

/**
 * @alias $.foo
 * @type {object}
 */
var foo = {};

$.foo = foo;
```
@name <namepath>

使用 @name 时，需要提供很多其他的注释，如 @type 等，因为JSDoc会忽略这部分代码

适用于在运行时才生成的函数等
```
/**
 * @name foo
 * @func
 * @param {string} a - 参数a
 */
eval('window.foo = function (a) {};');
```

@inheritdoc

继承父类的注释

/**
 * @class
 */
function myClass() {
    ...
}

/**
 * @method
 * @param {string} a - 参数a
 * @returns {boolean} 返回值
 */
myClass.prototype.foo = function (a) {
    ...
    return true;
}

/**
 * @class
 * @extends myClass
 */
function subClass() {
    ...
}

subClass.prototype = Object.create(myClass.prototype);

/**
 * @inheritdoc
 */
subClass.prototype.foo = function (a) {
    ...
    return true;
};

@mixin [<MixinName>]

表明当前对象的属性和方法可以被添加到另一个对象中

/**
 * @mixin
 * @property {string} a - 属性a
 * @property {number} b - 属性b
 */
var foo = {
    a: 'a',
    b: 1
}

@mixes <OtherObjectPath>

将带有 @mixin 标签的对象的属性和方法添加进来

/**
 * @mixin
 * @property {string} a - 属性a
 * @property {number} b - 属性b
 */
var foo = {
    a: 'a',
    b: 1
}

/**
 * @var {object}
 * @property {boolean} c - 属性c
 * @mixes foo
 */
var bar = {
    c: true
}

for (var key in foo) {
    var[key] = foo[key];
}

@see <namepath>

页面里超链接的作用

/**
 * @class
 */
function myClass() {
    /**
     * @member {string}
     */
    this.foo = 'a';
}

/**
 * @see myClass.foo
 */
var bar = myClass.foo;

{@link namepath or url}

可以理解为注释中内联的 @see

/**
 * @class
 */
function myClass() {
    ...
}

/**
 * @desc 这是{@link myClass}的一个实例 
 */
var foo = new myClass();