Fork me on GitHub

jsDoc学习-标签1

块标签(Block Tags)

@abstract

该成员(一般指父类的方法)必须在继承的子类中实现(或重写)。
别名:@virtual
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
/**
* 奶制品
* @constructor
*/
function DairyProduct () {}
/**
* 检查奶制品的状态
* @abstract
* @return {boolean}
*/
DairyProduct.prototype.isSolid = function () {
throw new Error('must be implemented by subclass!');
};

/**
* 牛奶
* @constructor
*/
function Milk () {}
Milk.prototype = new DairyProduct();
// 这里重写了父类的isSolid方法
Milk.prototype.isSolid = function () {
return false;
};
var dd = new Milk();
console.log(dd.isSolid()); // false

@access

指定该成员的访问级别(私有 private,公共 public,或保护 protected)
语法:@access <private|protected|public>
    @access private 等价于 @private;
    @access protected 等价于 @protected;
    @access public 等价于 @public;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
/**
* @constructor
*/
function Thingy () {
/** @access private */
var foo = 0;
/** @access protected */
this._bar = 1;
/** @access public */
this.pez = 2;
}
OR
/**
* @constructor
*/
function Thingy () {
/** @private */
var foo = 0;
/** @protected */
this._bar = 1;
/** @public */
this.pez = 2;
}

alias

标记成员有一个别名
语法:@alias <aliasNamepath>
例如,匿名的构造函数使用@alias。
1
2
3
4
5
6
7
8
9
10
11
Klass('trackr.CookieManager',
/**
* 匿名函数
* @alias trackr.CookieManager
* @param kv
*/
function (kv) {
/** trackr.CookieManager#value */
this.value = kv;
}
)
您也可以在一个立即调用的函数表达式(IIFE)中创建的成员中使用@alias标签。 @alias标签告诉JSDoc,这些成员都暴露在IIFE作用域之外的。 例如,命名空间的静态方法使用@alias。
1
2
3
4
5
6
7
8
9
10
11
12
/** @namespace */
var Apple = {};
(function (ns) {
/**
* @namespace
* @alias Apple.Core
*/
var core = {};
/** Documented as Apple.Core.seed */
core.speed = function () {};
ns.Core = core;
})(Apple);
对于那些对象字面量中定义的成员,可以使用@alias标签替代的@lends标记。 例如,对象常量使用@alias。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Documenting objectA with @alias
var objectA = (function() {
/**
* Documented as objectA
* @alias objectA
* @namespace
*/
/** @lends objectA */
var x = {
/**
* Documented as objectA.myProperty
* @member
*/
myProperty: 'foo'
};

return x;
})();

@auguments

@augments or@extends标签指明标识符继承自哪个父类,后面需要加父类名。
你可以使用这个标签来记录基于类和并基于原型的继承。
别名:@extends
语法:@auguments <namepath>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/**
* 动物
* @constructor
*/
function Animal () {
this.alive = true;
}

/**
* 鸭子
* @constructor
* @auguments Animal
*/
function Duck () {}
Duck.prototype = new Animal();
Duck.prototype.speak = function () {
if (this.alive) {
alert('Quack!');
}
};
var d = new Duck();
d.speak();

@author

@author标签标识一个项目的作者。
语法:@author <name> [<emailAddress>]
1
2
3
4
/**
* @author fanerge <fanerge@qq.com>
*/
function MyClass () {};

@borrows

@borrows标签允许您将另一个标识符的描述添加到你的当前描述。
语法:@borrows <that namepath> as <this namepath>
在这个例子中,"trstr"函数存在文档,但"util.trim"只是使用不同的名称引用相同的功能。
例如,复制trstr的文档描述给util.trim。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
/**
* @namespace
* @borrows trstr as trim
*/
var util = {
trim: trstr
};

/**
* Remove whitespace from around a string.
* @param {string} str
*/
function trstr(str) {
}

@callback

描述一个回调函数。@Callback标签提供回调函数(可传递给其他函数)的描述,包括回调的参数和返回值。
你可以包涵任何一个你能提供给@method标签。
语法:@callback <namepath>
例如,描述一个指定类回调。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
/**
* @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~requestCallback
* @param {number} responseCode
* @param {string} responseMessage
*/

@class

@class标签标明函数是一个构造器函数,意味着需要使用 new 关键字来返回一个实例,即使用 new 关键字实例化。
别名:@constructor
语法:@class [<type> <name>]
例如,一个函数构建一个Person实例
1
2
3
4
5
6
/**
* 创建一个人
* @class
*/
function Person () {}
var p = new Person();

@classdesc

@classdesc标签用于为类提供一个描述,这样和构造函数的描述区分开来。
@classdesc标签应该与 @class (或 @constructor)标签结合使用。
语法:@classdesc <some description>
如下所示,一个类有两个添加描述的地方,一个适用于函数本身,而另一个一般适用于类。
1
2
3
4
5
6
7
/**
* This is a description of the MyClass constructor function.
* @class
* @classdesc This is a description of the MyClass class.
*/
function MyClass() {
}

@constant

@constant 标签指明这个对象是一个常量。
语法:@constant [<type> <name>]    
例如,一个字符串常量表示红色。
1
2
3
4
5
/** @constant
@type {string}
@default
*/
const RED = 'FF0000';

@constructs

当使用对象字面量形式定义类(例如使用@lends标签)时,可使用@constructs标签标明这个函数用来作为类的构造实例。
语法:@constructs [name]
例如, @constructs 和 @lends 结合使用
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var Person = makeClass(
/** @lends Person.prototype */
{
/**
* @constructs
* @param name
*/
initialize: function (name) {
this.name = name;
},
/**
* @param msg
* @returns {*}
*/
say: function (msg) {
return `${this.name}says:${msg}`;
}
});
@copyright标签是用来描述一个文件的版权信息。一般和@file 标签结合使用。
语法:@copyright <some copyright text>
1
2
3
4
/**
* @file this is javascript
* @copyright fanerge 2017
*/

@default

@default标签可以让你记录标识的赋值。
可以在标签后面跟上他的值,或者当值是一个唯一被分配的简单值(可以是:一个字符串,数字,布尔值或null)的时候,你可以让JSDoc从源代码中获取值,自动记录 。
别名:defaultvalue
语法:@default [<some value>]
在本实例中,一个常量被记录。该常数的值为0xff0000。通过添加@default标签,这个值将自动添加到文档。
1
2
3
4
5
/**
* @constant
* @default
*/
const RED = '0xff0000';

@deprecated

@deprecated 标签指明一个标识在你代码中已经被弃用。
语法:@deprecated [<some text>]
例如,描述一个old函数从2.0版本开始已经被弃用
1
2
3
4
/**
* @deprecated since version 2.0
*/
function old () {}

@description

@description标签允许您提供一般描述。
该说明可能包括HTML标签。如果Markdown 插件启用的话,它也可包括Markdown格式。
别名:@desc
语法:@description <some description>
例如,不用@description标签描述一个标识
1
2
3
4
5
6
7
8
9
/**
* Add two numbers.
* @param {number} a
* @param {number} b
* @returns {number}
*/
function add(a, b) {
return a + b;
}
例如,用@description标签描述一个标识
1
2
3
4
5
6
7
8
9
/**
* @param {number} a
* @param {number} b
* @returns {number}
* @description Add two numbers.
*/
function add(a, b) {
return a + b;
}

@enum

@enum标签描述一个静态属性值的全部相同的集合。
枚举类似一个属性的集合,除了枚举自己的描述注释之外,属性都记录在容器内部的注释中。
通常这种标签是与@ReadOnly结合使用,作为一个枚举通常表示常量的集合。
语法:@enum [<type>]
例如,一个数字枚举,表示的3种状态
1
2
3
4
5
6
7
8
9
10
11
12
/**
* Enum for tri-state values.
* @readonly
* @enum {number}
*/
var triState = {
/** The true value */
TRUE: 1,
FALSE: -1,
/** @type {boolean} */
MAYBE: true
};

@event

描述一个事件。@event标签允许您描述一个可触发的事件,一个典型的事件是由对象定义的一组属性来表示。
标签来定义事件的具体类型,您可以使用@fires标记,以表明这个种方法可以触发该事件。
你还可以使用@listens标签,以指示表明用这个表示来侦听该事件。    
语法:@event <className>#[event:]<eventName>
例如,描述一个作为事件的行数
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/**
* Throw a snowball.
*
* @fires Hurl#snowball
*/
Hurl.prototype.snowball = function() {
/**
* Snowball event.
*
* @event Hurl#snowball
* @type {object}
* @property {boolean} isPacked - Indicates whether the snowball is tightly packed.
*/
this.emit('snowball', {
isPacked: this._snowball.isPacked
});
};

@example

提供一个如何使用描述项的例子。跟随此标签的文字将显示为高亮代码。
1
2
3
4
5
6
7
8
9
10
11
12
13
/**
* Solves equations of the form a * x = b
* @example
* // returns 2
* globalNS.method1(5, 10);
* @example
* // returns 3
* globalNS.method(5, 15);
* @returns {Number} Returns the value of x for the equation.
*/
globalNS.method1 = function (a, b) {
return b / a;
};

@exports

@exports标签描述由JavaScript模块的exports或module.exports属性导出的任何内容。
语法:@exports <moduleName>
1
2
3
4
5
6
7
8
9
/**
* A module that says hello!
* @module hello/world
*/

/** Say hello. */
exports.sayHello = function() {
return 'Hello world';
};

@external

@external标签用来标识一个在当前包外部定义的类,命名空间,或模块。
通过使用这个标签,你可以描述你的包的外部标识的扩展,或者您也可以提供关于 外部标识的相关信息给你的包的使用者。
你也可以在任何其他JSDoc标签中引用外部标识的namepath(名称路径)。
外部标识引用的路径名 始终需要使用external:前缀:(例如{@link external:Foo}或@augments external:Foo)。 但是,你可以省略@external标记的这个前缀。
别名:@host
下面的示例演示如何描述内置的String对象作为external,新的实例方法external:String#rot13
1
2
3
4
5
6
7
8
9
10
11
12
13
/**
* The built in string object.
* @external String
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String|String}
*/

/**
* Create a ROT13-encoded version of the string. Added by the `foo` package.
* @function external:String#rot13
* @example
* var greeting = new String('hello world');
* console.log( greeting.rot13() ); // uryyb jbeyq
*/

参考文档:
jsDoc文档

-------------本文结束感谢您的阅读,如果本文对你有帮助就记得给个star-------------
Donate comment here