Как указать, что параметр является необязательным, используя встроенный JSDoc?

119

Согласно вики JSDoc для @param вы можете указать, что @param является необязательным, используя 

/**
    @param {String} [name]
*/
function getPerson(name) {
}

и вы можете указать встроенный параметр, используя

function getPerson(/**String*/ name) {
}

И я могу объединить их следующим образом, и это нормально.

/**
    @param [name]
*/
function getPerson(/**String*/name) {
}

Но я хотел бы знать, есть ли способ сделать все это, если это возможно.

javascript google-closure-compiler jsdoc studgeek
источник

Ответы:

123

Из официальной документации :

Необязательный параметр

Необязательный параметр с именем foo.

@param {number} [foo]
// or:
@param {number=} foo

Необязательный параметр foo со значением по умолчанию 1.

@param {number} [foo=1]
Черни
источник
7
Я спрашивал, как это сделать встроенным. Приведенный вами пример похож на тот, который я показал в своем вопросе.
Studgeek
67

После некоторого раскопок я обнаружил, что они тоже в порядке

/**
 * @param {MyClass|undefined}
 * @param {MyClass=}
 * @param {String} [accessLevel="author"] The user accessLevel is optional.
 * @param {String} [accessLevel] The user accessLevel is optional.
 */

Просто немного более привлекательно, чем function test(/**String=*/arg) {}

vvMINOvv
источник
9
Они действительны (и задокументированы в справке JSDoc), но они не встроены - это то, что я искал.
Studgeek
Вопрос касается встроенной нотации JSDoc. Это интересная информация, но не отвечает на вопрос,
Кен Беллоуз,
51

Я нашел способ сделать это с помощью выражений типов Google Closure Compiler . Вы ставите знак равенства после типа: function test(/**String=*/arg) {}

studgeek
источник
10
WebStorm / IntellIDEA поддерживает эту нотацию
Питер Арон Зентаи
3
Да, поэтому я думаю, что он получил достаточно одобрения, чтобы отметить его как ответ.
Studgeek
4
@PeterAronZentai, я добавлю, что WebStorm / IntelliIDEA поддерживает его, потому что я поместил для него запрос функции :). Теперь они поддерживают большинство выражений типов Google Closure Compiler, и это здорово.
Studgeek
1
Не работает для меня необязательный второй параметр.
DaveWalley
3

Если вы используете комментарии встроенного типа для аргументов функции и задаетесь вопросом, как пометить аргумент функции как необязательный в этой нотации, я обнаружил, что просто присвоение значений по умолчанию необязательным аргументам сработало. Если вы хотите, чтобы значение по умолчанию было, undefinedвы также должны указать его явно, иначе аргумент не будет отмечен как необязательный (даже если ему предшествуют уже необязательные аргументы):

function demo(
  /** @type {String} */ mandatory,
  /** @type {Number} */ optional1 = 0,
  /** @type {Number} optional2 = undefined,
)

Если вы наведете курсор на demoсвою среду IDE, вы должны увидеть и то, optional1и другое, и optional2теперь они будут отображаться как необязательные. В VSCode это обозначается значком ?после имени аргумента (нотация TypeScript). Если вы удалите = undefinedиз, optional2вы увидите только optional1опциональность, что, конечно, бессмысленно, поэтому значение по умолчанию здесь должно быть явным, как я упоминал в предыдущем абзаце.

Томаш Хюбельбауэр
источник