JSDoc 中文网

语法

¥Syntax

@type {typeName}

概述

¥Overview

@type 标记允许你提供类型表达式，用于标识符号可能包含的值的类型或函数返回的值的类型。你还可以将类型表达式与许多其他 JSDoc 标记一起包含，例如 @param tag。

¥The @type tag allows you to provide a type expression identifying the type of value that a symbol may contain, or the type of value returned by a function. You can also include type expressions with many other JSDoc tags, such as the @param tag.

类型表达式可以包含符号的 JSDoc 名称路径（例如，myNamespace.MyClass）；内置 JavaScript 类型（例如 string）；或这些的组合。你可以使用任何 Google Closure 编译器类型表达式 以及 JSDoc 特有的其他几种格式。

¥A type expression can include the JSDoc namepath to a symbol (for example, myNamespace.MyClass); a built-in JavaScript type (for example, string); or a combination of these. You can use any Google Closure Compiler type expression, as well as several other formats that are specific to JSDoc.

如果 JSDoc 确定类型表达式无效，它将显示错误并停止运行。你可以通过使用 --lenient 选项运行 JSDoc 将此错误转变为警告。

¥If JSDoc determines that a type expression is invalid, it will display an error and stop running. You can turn this error into a warning by running JSDoc with the --lenient option.

注意：JSDoc 3.2 及更高版本中提供了对 Google Closure Compiler 样式类型表达式的完全支持。JSDoc 的早期版本包括对 Closure Compiler 类型表达式的部分支持。

¥Note: Full support for Google Closure Compiler-style type expressions is available in JSDoc 3.2 and later. Earlier versions of JSDoc included partial support for Closure Compiler type expressions.

每种类型都通过使用下述格式之一提供类型表达式来指定。在适当的情况下，JSDoc 将自动创建指向其他符号文档的链接。例如，如果该符号已被记录，@type {MyClass} 将链接到 MyClass 文档。

¥Each type is specified by providing a type expression, using one of the formats described below. Where appropriate, JSDoc will automatically create links to the documentation for other symbols. For example, @type {MyClass} will link to the MyClass documentation if that symbol has been documented.

类型名称 语法示例 描述
符号名称（名称表达式） 
{boolean}
{myNamespace.MyClass}

指定符号的名称。如果你已记录该符号，JSDoc 会创建指向该符号文档的链接。

多种类型（类型联合）
这可以是数字或布尔值。

这意味着一个值可以具有多种类型之一，整个类型列表括在括号中并用 | 分隔。

数组和对象（类型应用和记录类型）
MyClass 实例的数组。
{Array.<MyClass>}
// or:
{MyClass[]}
具有字符串键和数字值的对象：
{Object.<string, number>}
名为 'myObj' 的对象，具有属性 'a'（数字）、'b'（字符串）和 'c'（任何类型）。

{{a: number, b: string, c}} myObj // or: {Object} myObj {number} myObj.a {string} myObj.b {*} myObj.c

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

你还可以通过将 [] 附加到数组中包含的类型来指示数组。例如，表达式 string[] 表示字符串数组。

对于具有一组已知属性的对象，你可以使用 Closure Compiler 的语法来记录记录类型。你可以单独记录每个属性，这使你能够提供有关每个属性的更详细信息。

可空类型
数字或空值。

这表明该类型要么是指定类型，要么是 null。

不可为 null 的类型
一个数字，但决不为空。

表示该值是指定类型，但不能是 null。

该类型的变量数
该函数接受数量可变的数字参数。
@param {...number} num

指示该函数接受可变数量的参数，并指定参数的类型。例如： 

/**

 * 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&lt;n; i++) {
        t += arguments[i];
    }
    return t;
}
可选参数
名为 foo 的可选参数。
@param {number} [foo]
// or:
@param {number=} foo
可选参数 foo，默认值为 1。
@param {number} [foo=1]

表示该参数是可选的。当使用 JSDoc 的可选参数语法时，你还可以指示省略参数时将使用的值。

回调 
/**

 * @callback myCallback

 * @param {number} x - ...
 */

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

使用 @callback 标记记录回调。语法与 @typedef 标记相同，只是回调的类型始终为 "功能。"

类型定义
记录具有属性 '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;

你可以使用 @typedef 标记记录复杂类型，然后在文档中的其他位置引用类型定义。

示例

¥Examples

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

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

¥In many cases, you can include a type expression as part of another tag, rather than including a separate @type tag in your JSDoc comment.

类型表达式可以伴随许多标签。
/**

 * @type {number}

 * @const
 */
var FOO = 1;

// same as:

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