@use JSDoc

同义词

概述

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

@param 标记要求您指定要记录的参数的名称。您还可以包含参数的类型（用大括号括起来）和参数的描述。

参数类型可以是内置的 JavaScript 类型，例如 string 或 Object，也可以是代码中另一个符号的 JSDoc 名称路径。如果您已为该名称路径处的符号编写文档，JSDoc 将自动链接到该符号的文档。您还可以使用类型表达式来指示，例如，一个参数不可为 null 或可以接受任何类型；有关详细信息，请参阅 @type 标记文档。

如果您提供描述，可以通过在描述前插入连字符来使 JSDoc 注释更具可读性。请务必在连字符前后包含空格。

示例

名称、类型和描述

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

仅名称
/**
 * @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);
}

您可以在描述前添加连字符以使其更具可读性。请务必在连字符前后包含空格。

名称、类型和描述，在描述前有连字符
/**
 * @param {string} somebody - Somebody's name.
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}

具有属性的参数

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

记录参数的属性
/**
 * 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) {
    // ...
};

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

记录解构参数
/**
 * 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 的数组参数语法结合使用。例如，如果可以将多个员工分配给一个项目

记录数组中值的属性
/**
 * 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) {
    // ...
};

可选参数和默认值

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

可选参数（使用 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);
}

多种类型和可重复参数

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

允许一种类型或另一种类型（类型联合）
/**
 * @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 标记 定义一个回调类型，然后将回调类型包含在 @param 标记中。

接受回调的参数
/**
 * 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
};