@param

Оглавление

• Синонимы
• Обзор
• Примеры
  • Имена, типы и описания
  • Параметры с свойствами
  • Необязательные параметры и значения по умолчанию
  • Несколько типов и повторяющиеся параметры
  • Функции обратного вызова
• Связанные ссылки

Синонимы

• @arg
• @argument

Обзор

Тег @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) {
    // ...
};

Необязательные параметры и значения по умолчанию

Следующие примеры показывают, как указать, что параметр является необязательным и имеет значение по умолчанию.

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

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

Несколько типов и повторяющиеся параметры

Следующие примеры показывают, как использовать выражения типа для указания того, что параметр может принимать несколько типов (или любой тип), и что параметр может быть предоставлен более одного раза. См. документацию тега @type для получения подробной информации о выражениях типа, поддерживаемых JSDoc.

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

Связанные ссылки

• @callback
• @returns
• @type
• @typedef