JSDoc 中文网

Synonyms

概述

¥Overview

@param 标签提供函数参数的名称、类型和描述。

¥The @param tag provides the name, type, and description of a function parameter.

@param 标签要求你指定正在记录的参数的名称。你还可以包含用大括号括起来的参数类型以及参数的说明。

¥The @param tag requires you to specify the name of the parameter you are documenting. You can also include the parameter's type, enclosed in curly brackets, and a description of the parameter.

参数类型可以是内置 JavaScript 类型，例如 string 或 Object，或者代码中另一个符号的 JSDoc 名称路径。如果你在该名称路径上编写了该符号的文档，JSDoc 将自动链接到该符号的文档。例如，你还可以使用类型表达式来指示参数不可为空或可以接受任何类型；详细信息请参见 @type 标签文档。

¥The parameter type can be a built-in JavaScript type, such as string or Object, or a JSDoc namepath to another symbol in your code. If you have written documentation for the symbol at that namepath, JSDoc will automatically link to the documentation for that symbol. You can also use a type expression to indicate, for example, that a parameter is not nullable or can accept any type; see the @type tag documentation for details.

如果你提供描述，则可以通过在描述前插入连字符来使 JSDoc 注释更具可读性。确保连字符前后各有一个空格。

¥If you provide a description, you can make the JSDoc comment more readable by inserting a hyphen before the description. Be sure to include a space before and after the hyphen.

示例

¥Examples

名称、类型和描述

¥Names, types, and descriptions

以下示例显示如何在 @param 标记中包含名称、类型和描述。

¥The following examples show how to include names, types, and descriptions in a @param tag.

仅名称
/**

 * @param somebody
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}
名称和类型
/**

 * @param {string} somebody
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}
名称、类型和描述
/**

 * @param {string} somebody Somebody's name.
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}

你可以在描述之前添加连字符以使其更具可读性。确保连字符前后各有一个空格。

¥You can add a hyphen before the description to make it more readable. Be sure to include a space before and after the hyphen.

名称、类型和描述，描述前有连字符
/**

 * @param {string} somebody - Somebody's name.
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}

具有属性的参数

¥Parameters with properties

如果参数预计具有特定属性，你可以通过提供额外的 @param 标记来记录该属性。例如，如果 employee 参数预计具有 name 和 department 属性，你可以按如下方式记录它：

¥If a parameter is expected to have a specific property, you can document that property by providing an additional @param tag. For example, if an employee parameter is expected to have name and department properties, you can document it as follows:

记录参数的属性
/**

 * Assign the project to an employee.

 * @param {Object} employee - The employee who is responsible for the project.

 * @param {string} employee.name - The name of the employee.

 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function(employee) {
    // ...
};

如果参数在没有显式名称的情况下被解构，你可以为该对象指定一个适当的名称并记录其属性。

¥If a parameter is destructured without an explicit name, you can give the object an appropriate one and document its properties.

记录解构参数
/**

 * Assign the project to an employee.

 * @param {Object} employee - The employee who is responsible for the project.

 * @param {string} employee.name - The name of the employee.

 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function({ name, department }) {
    // ...
};

你还可以将此语法与 JSDoc 的数组参数语法结合起来。例如，如果可以将多个员工分配给一个项目：

¥You can also combine this syntax with JSDoc's syntax for array parameters. For example, if multiple employees can be assigned to a project:

记录数组中值的属性
/**

 * Assign the project to a list of employees.

 * @param {Object[]} employees - The employees who are responsible for the project.

 * @param {string} employees[].name - The name of an employee.

 * @param {string} employees[].department - The employee's department.
 */
Project.prototype.assign = function(employees) {
    // ...
};

可选参数和默认值

¥Optional parameters and default values

以下示例显示如何指示参数是可选的并且具有默认值。

¥The following examples show how to indicate that a parameter is optional and has a default value.

可选参数（使用 JSDoc 语法）
/**

 * @param {string} [somebody] - Somebody's name.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    }
    alert('Hello ' + somebody);
}
可选参数（使用 Google Closure Compiler 语法）
/**

 * @param {string=} somebody - Somebody's name.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    }
    alert('Hello ' + somebody);
}
可选参数和默认值
/**

 * @param {string} [somebody=John Doe] - Somebody's name.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    }
    alert('Hello ' + somebody);
}

多种类型和可重复的参数

¥Multiple types and repeatable parameters

以下示例演示如何使用类型表达式来指示参数可以接受多种类型（或任何类型），并且可以多次提供参数。有关 JSDoc 支持的类型表达式的详细信息，请参阅 @type 标签文档。

¥The following examples show how to use type expressions to indicate that a parameter can accept multiple types (or any type), and that a parameter can be provided more than once. See the @type tag documentation for details about the type expressions that JSDoc supports.

允许一种类型或另一种类型（类型联合）
/**

 * @param {(string|string[])} [somebody=John Doe] - Somebody's name, or an array of names.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    } else if (Array.isArray(somebody)) {
        somebody = somebody.join(', ');
    }
    alert('Hello ' + somebody);
}
允许任何类型
/**

 * @param {*} somebody - Whatever you want.
 */
function sayHello(somebody) {
    console.log('Hello ' + JSON.stringify(somebody));
}
允许重复参数
/**

 * 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;
}

回调函数

¥Callback functions

如果参数接受回调函数，则可以使用 @callback 标签 定义回调类型，然后将回调类型包含在 @param 标记中。

¥If a parameter accepts a callback function, you can use the @callback tag to define a callback type, then include the callback type in the @param tag.

接受回调的参数
/**

 * This callback type is called `requestCallback` and is displayed as a global symbol.

 *  * @callback requestCallback

 * @param {number} responseCode

 * @param {string} responseMessage
 */

/**

 * Does something asynchronously and executes the callback on completion.

 * @param {requestCallback} cb - The callback that handles the response.
 */
function doSomethingAsynchronously(cb) {
    // code
};