Как указать параметр необязательно с помощью встроенного JSDoc?

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

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

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

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

И я могу объединить их, как показано ниже:

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

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

Ответ 1

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

Ответ 2

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

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

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

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

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

@param {number} [foo=1]

Ответ 3

После некоторого рытья я обнаружил, что это нормально, а

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

Ответ 4

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

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

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