Особенности @param в JsDoc

В комментариях я использую разметку JsDoc. Есть утилиты, которые автоматически строят документацию, основываясь на этой разметке. Ещё она польза заключается в том, что статические анализаторы в IDE умею проверять использование прокомментированных функций.

С перечнем аннотаций, их параметрами и примерами использования можно ознакомиться, например, в документации к генератору jsdoc-toolkit.

Самой популярной, пожалуй, аннотацией является @param.

@param {paramType} paramName paramDescription
  • paramType — опциональный: ожидаемый тип параметра;
  • paramName — обязательный: название параметра;
  • paramDescription — опциональный: описание параметра.

В JS нет строгой типизации параметров функции. В одном случае, например, тип параметра может быть числом, а в другом — строка. Все ожидаемые типы перечисляются с разделителем |.

/**
 * @param {Number|String} value
 */
function showValue(value) {
    alert(value);
}

А ещё параметры функции могут быть опциональными. В этом случае название параметра заключаются в квадратные скобки.

var uidx = 1;
/**
 * Generate an id that is unique among the application
 * @param {String} [prefix] optional guid prefix
 */
function guid(prefix) {
    return (prefix || 'app') + '-' + uidx++;
}

Теперь статический анализатор не будет требовать, чтобы функция guid обязательно вызывалась с параметром. Но покажет предупреждение, если будет указано больше одного параметра.