JSDoc中文文档(@use JSDoc)

JSDoc @type 标签

目录

语法

@type {typeName}

概述

@type标签允许你提供一个表达式，用于标识一个标识符可能包含的值的类型，或由函数返回值的类型。您还可以将其包含与其他JSDoc标签类型的表达式结合使用，如@param 标签。

类型表达式可以包括标识符的namepath（例如，myNamespace.MyClass）;一个内置的JavaScript类型（例如，string）;或这些的组合。你可以使用任何Google Closure Compiler 的类型表达式，还有其他几种JSDoc所特有的格式。

如果JSDoc确定一个类型表达式是无效的，它会显示一个错误并停止运行。您可以通过与--lenient选项运行JSDoc把这个错误变成警告。

注意: 在JSDoc3.2及更高版本完全支持Google Closure Compiler风格的类型表达式。早期版本的JSDoc支持部分的Google Closure Compiler类型表达式。

每种类型是通过使用下面描述的格式之一，提供一个类型表达式指定的。 在适当情况下，JSDoc将自动创建链接到其他标识符的文档。例如，@type {MyClass}将链接到MyClass的文档，如果该标识符已经被文档化。

Type name Syntax examples Description
Symbol name (name expression) 
{boolean}
{myNamespace.MyClass}

指定符号的名称。 如果标识符已经被文档化，JSDoc将创建一个链接到该标识符的文档。

Multiple types (type union)
示例: This can be a number or a boolean.
{(number|boolean)}

这意味着值可能是几种类型中的一种，用括号括起来，并用"|"分隔类型的完整列表。

Arrays and objects (type applications and record types)
示例: An array of MyClass instances.
{Array.<MyClass>}
// or:
{MyClass[]}
示例: An object with string keys and number values:
{Object.<string, number>}
示例: An object called 'myObj' with properties 'a' (a number), 'b' (a string) and 'c' (any type). 
{{a: number, b: string, c}} myObj
// or:
{Object} myObj
{number} myObj.a
{string} myObj.b
{*} myObj.c

JSDoc支持 Closure Compiler 语法定义的数组和对象类型。

还可以通过array后面附加[]指示包含在数组中的类型。例如，表达式string[]表示字符串数组。

对于具有一组已知的属性的对象，你可以使用 Closure Compiler 语法文档化标注的类型。您可以分别描述每个属性，这使您能够提供有关每个属性的更多详细信息。
Nullable type
示例: A number or null.
{?number}

指明类型为指定的类型，或者为 null。

Non-nullable type
示例: A number, but never null.
{!number}

指明类型为指定的类型，但是绝对不会是null。

Variable number of that type
示例: This function accepts a variable number of numeric parameters.
@param {...number} num

Indicates that the function accepts a variable number of parameters, and specifies a type for the parameters. For example: 

/**
 * Returns the sum of all numbers passed to the function.
 * @param {...number} num A positive or negative number
 */
function sum(num) {
    var i=0, n=arguments.length, t=0;
    for (; i<n; i++) {
        t += arguments[i];
    }
    return t;
}
Optional parameter
示例: An optional parameter named foo.
@param {number} [foo]
// or:
@param {number=} foo
示例: An optional parameter foo with default value 1.
@param {number} [foo=1]

Indicates that the parameter is optional. When using JSDoc's syntax for optional parameters, you can also indicate the value that will be used if a parameter is omitted.

Callbacks 
/**
 * @callback myCallback
 * @param {number} x - ...
 */


/** @type {myCallback} */
var cb;

Document a callback using the @callback tag. The syntax is identical to the @typedef tag, except that a callback's type is always "function."

Type definitions
示例: Documenting a type with properties 'id', 'name', 'age'.
/**
 * @typedef PropertiesHash
 * @type {object}
 * @property {string} id - an ID.
 * @property {string} name - your name.
 * @property {number} age - your age.
 */


/** @type {PropertiesHash} */
var props;

You can document complex types using the @typedef tag, then refer to the type definition elsewhere in your documentation.

示例

示例: Example
/** @type {(string|Array.)} */
var foo;
/** @type {number} */
var bar = 1;

在许多情况下，您可以包含一个类型表达式作为另一个标签的一部分，而不是在你的JSDoc注释块中包含独立@type标签。

示例: 类型表达式可以有多个标签
/**
 * @type {number}
 * @const
 */
var FOO = 1;

// same as:

/** @const {number} */
var FOO = 1;