Fork me on GitHub

jsDoc学习-标签3

@override

@override标签指明一个标识符覆盖其父类同名的标识符。
下面的例子说明一个方法如何重写父类的方法。
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
/**
* @classdesc Abstract class representing a network connection.
* @class
*/
function Connection() {}
/**
* Open the connection.
*/
Connection.prototype.open = function() {
// ...
};
/**
* @classdesc Class representing a socket connection.
* @class
* @augments Connection
*/
function Socket() {}
/**
* Open the socket.
* @override
*/
Socket.prototype.open = function() {
// ...
};

@param

@param标签提供了对某个函数的参数的各项说明,包括参数名、参数数据类型、描述等。
别名:@arg @argument
下面的示例演示如何在 @param标签中包含名称,类型,和说明。
1
2
3
4
5
6
/**
* @param somebody
*/
function sayHello(somebody) {
alert('Hello ' + somebody);
}

@private

@private标签标记标识符为私有,或者不做一般用途使用。
私有成员不会在生成文档中输出任何内容,除非JSDoc使用 -p/--private 命令行选项运行。
语法:@private
在下面的例子中,Documents和Documents.Newspaper会被输出到生成的文档中,但是Documents.Diary不会。
1
2
3
4
5
6
7
8
9
10
11
12
/** @namespace */
var Documents = {
/**
* An ordinary newspaper.
*/
Newspaper: 1,
/**
* My diary.
* @private
*/
Diary: 2
};

@property

@property标签很容易描述类,命名空间或其它对象的静态属性列表。
别名:@prop
例如,描述命名空间的默认属性及嵌套属性:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/**
* @namespace
* @property {object} defaults - The default values for parties.
* @property {number} defaults.players - The default number of players.
* @property {string} defaults.level - The default level for the party.
* @property {object} defaults.treasure - The default treasure.
* @property {number} defaults.treasure.gold - How much gold the party starts with.
*/
var config = {
defaults: {
players: 1,
level: 'beginner',
treasure: {
gold: 0
}
}
};

@protected

@protected标签标记标识符为受保护的,通常情况下,受保护的成员只能在被继承的子类中或在模块内部可以访问。
语法:@protected [{typeExpression}]
在下面的例子中,该实例成员Thingy#_bar会被导出到生成的文档中,但使用注释说明它是被保护的。
1
2
3
4
5
/** @constructor */
function Thingy() {
/** @protected */
this._bar = 1;
}

@public

@public标签标记标识符为公开的。    
1
2
3
4
5
6
7
8
9
10
11
12
13
/**
* The Thingy class is available to all.
* @public
* @class
*/
function Thingy() {
/**
* The Thingy~foo member. Note that 'foo' is still an inner member
* of 'Thingy', in spite of the @public tag.
* @public
*/
var foo = 0;
}

@readonly

标记一个标识符为只读。jsdoc不会检查某个代码是否真是只读的,只要标上@readonly,在文档中就体现为只读的。
例如,给getter标记为只读
1
2
3
4
5
6
7
8
9
10
11
12
13
/**
* Options for ordering a delicious slice of pie.
* @namespace
*/
var pieOptions = {
/**
* A la mode.
* @readonly
*/
get aLaMode() {
return this.plain + ' with ice cream';
}
};

@requires

@requires标签可以记录一个模块需要的依赖项。一个JSDoc注释块可以有多个@require标签。
模块名可以被指定为 "moduleName" 或者 "module:moduleName";这两种形式将被解析为模块。
语法:@requires <someModuleName>
例如,使用@requires 标签
1
2
3
4
5
6
7
8
/**
* This class requires the modules {@link module:xyzcorp/helper} and
* {@link module:xyzcorp/helper.ShinyWidget#polish}.
* @class
* @requires module:xyzcorp/helper
* @requires xyzcorp/helper.ShinyWidget#polish
*/
function Widgetizer() {}

@returns

@returns 标签描述一个函数的返回值。语法和@param类似。
别名:@return
返回值的类型
1
2
3
4
5
6
7
8
9
/**
* Returns the sum of a and b
* @param {Number} a
* @param {Number} b
* @returns {Number}
*/
function sum(a, b) {
return a + b;
}

@see

@see标签表示可以参考另一个标识符的说明文档,或者一个外部资源。
语法:@see <namepath>
      @see <text>
1
2
3
4
5
6
/**
* Both of these will link to the bar function.
* @see {@link bar}
* @see bar
*/
function foo() {}

@since

@since标签标明一个类,方法,或其它标识符是在哪个特定版本开始添加进来的。
语法:@since <versionDescription>
例如,使用@since标签:
1
2
3
4
5
/**
* Provides access to user information.
* @since 1.0.1
*/
function UserRecord() {}

@static

@static标签标明一个在父类中的标识符不需实例即可使用。
例如,在一个虚拟注释中使用@static    
1
2
3
4
5
6
/** @namespace MyNamespace */
/**
* @function myFunction
* @memberof MyNamespace
* @static
*/

@summary

@summary标签是完整描述的一个简写版本。它可以被添加到任何的doclet。
语法:@summary Summary goes here.
1
2
3
4
5
6
7
/**
* A very long, verbose, wordy, long-winded, tedious, verbacious, tautological,
* profuse, expansive, enthusiastic, redundant, flowery, eloquent, articulate,
* loquacious, garrulous, chatty, extended, babbling description.
* @summary A concise summary.
*/
function bloviate() {}

@this

@this标签指明this关键字的指向。
语法:@this <namePath>
在下面的例子中,@this标签迫使"this.name"被描述为"Greeter#name",而不是全局变量"name"。
1
2
3
4
5
6
7
8
9
10
/** @constructor */
function Greeter(name) {
setName.apply(this, name);
}
/** @this Greeter */
function setName(name) {
/** document me */
this.name = name;
}

@throws

@throws标签可以让你描述函数可能会抛出的错误。在一个JSDoc注释块中您可以包含多个@throws标签。
语法:@throws free-form description
      @throws {<type>}
      @throws {<type>} free-form description
例如,在type中使用@throws标签:
1
2
3
4
/**
* @throws {InvalidArgumentException}
*/
function foo(x) {}

@todo

@todo标签可以让你记录要完成的任务。在一个JSDoc注释块中您可以包含多个@todo标签。
语法:@todo text describing thing to do.
1
2
3
4
5
6
7
/**
* @todo Write the documentation.
* @todo Implement this function.
*/
function foo() {
// write me
}

@tutorial

@tutorial 标签插入一个指向向导教程的链接,作为文档的一部分。
语法:@tutorial <tutorialID>
在下面的例子中,MyClass的文档将链接到tutorial-1 和 tutorial-2标识符的教程。
1
2
3
4
5
6
7
/**
* Description
* @class
* @tutorial tutorial-1
* @tutorial tutorial-2
*/
function MyClass() {}

@type

@type标签允许你提供一个表达式,用于标识一个标识符可能包含的值的类型,或由函数返回值的类型。
语法:@type {typeName1 | typeName2}
1
2
3
4
/** @type {(string|Array.<string>)} */
var foo;
/** @type {number} */
var bar = 1;

@typedef

@typedef标签在描述自定义类型时是很有用的,特别是如果你要反复引用它们的时候。
语法:@typedef [<type>] <namepath>
这个例子定义了一个联合类型的参数,表示可以包含数字或字符串。
1
2
3
4
/**
* A number, or a string containing a number.
* @typedef {(number|string)} NumberLike
*/

@variation

描述: 区分具有相同名称的不同的对象。
语法:@variation <variationNumber>

@version

@version标签后面的文本将被用于表示该项的版本。    
1
2
3
4
5
6
7
/**
* @version 1.2.3
* @tutorial solver
*/
function solver(a, b) {
return b / a;
}

内联标签(inline Tags)

{@link}内联标签创建一个链接到您指定的namepath或URL。当您使用{@link}标签,还可以提供几种不同的格式的链接文本。
如果你不提供任何链接文本,JSDoc使用namepath或URL作为链接文字。
别名:@linkcode  @linkplain
语法:{@link namepathOrURL}
      [link text]{@link namepathOrURL}
      {@link namepathOrURL|link text}
      {@link namepathOrURL link text (after the first space)}
下面的例子显示了提供给{@link} 标签链接文本的所有方式
1
2
3
4
5
6
/**
* See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
* Also, check out {@link http://www.google.com|Google} and
* {@link https://github.com GitHub}.
*/
function myFunction() {}

@tutorial

{@tutorial}行内标签创建一个链接到您指定的教程标识符。当您使用{@tutorial}标签,您也可以提供几种不同的格式的链接文本。
如果你不提供任何链接文本,JSDoc使用本教程的标题作为链接文字。
语法:{@tutorial tutorialID}
      [link text]{@tutorial tutorialID}
      {@tutorial tutorialID|link text}
      {@tutorial tutorialID link text (after the first space)}
下面的例子显示了提供给{@tutorial}标签链接文本的所有方式
1
2
3
4
5
6
/**
* See {@tutorial gettingstarted} and [Configuring the Dashboard]{@tutorial dashboard}.
* For more information, see {@tutorial create|Creating a Widget} and
* {@tutorial destroy Destroying a Widget}.
*/
function myFunction() {}

参考文档:
jsDoc文档

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