@param (synonyms: @arg, @argument)

.. @param::

同义词

@arg, @argument

概述

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

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.

The parameter type can be a built-in JavaScript type, such as string or Object, or a 在JSDoc 3中使用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 for details.

如果您提供描述, 则可以通过在描述之前插入连字符来使JSDoc注释更具可读性. 务必在连字符前后加一个空格.

示例

Names, types, and descriptions

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

仅限姓名

/**
 * @param somebody
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}

Name and type

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

Name, type, and description

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

您可以在说明之前添加连字符, 以使其更具可读性. 务必在连字符前后加一个空格.

名称, 类型和描述, 在描述之前用连字符表示

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

Parameters with properties

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:

Documenting a parameter’s 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(employee) {
    // ...
};

如果参数在没有显式名称的情况下被解构, 则可以为对象提供适当的参数并记录其属性.

Documenting a destructuring parameter

/**
 * 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的数组参数语法结合使用. 例如, 如果可以为项目分配多个员工:

Documenting properties of values in an array

/**
 * 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.

An optional parameter (using JSDoc syntax)

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

An optional parameter (using Google Closure Compiler syntax)

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

An optional parameter and default value

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

Multiple types and repeatable parameters

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 for details about the type expressions that JSDoc supports.

Allows one type OR another type (type union)

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

Allows any type

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

Allows a parameter to be repeated

/**
 * 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

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

Parameters that accept a callback

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

.. @arg::

同义词

@param

.. @argument::

同义词

@param