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 名称路径。如果你已经为该 namepath 下的符号编写了文档，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
};