Como indicar que o parâmetro é opcional usando JSDoc embutido?

119

De acordo com o wiki JSDoc para @param, você pode indicar que um @param é opcional usando 

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

e você pode indicar um parâmetro embutido usando

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

E posso combiná-los da seguinte forma, o que funciona bem.

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

Mas gostaria de saber se existe uma maneira de fazer tudo inline, se possível.

javascript google-closure-compiler jsdoc Studgeek
fonte

Respostas:

123

Da documentação oficial :

Parâmetro opcional

Um parâmetro opcional denominado foo.

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

Um parâmetro opcional foo com valor padrão 1.

@param {number} [foo=1]
Czerny
fonte
7
Eu estava perguntando como fazer isso inline. O exemplo que você está fornecendo parece ser o mesmo que mostrei na minha pergunta.
Studgeek,
67

Depois de alguma escavação, descobri que eles também estão ok

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

Apenas um pouco mais atraente do que visualmente function test(/**String=*/arg) {}

vvMINOvv
fonte
9
Eles são válidos (e documentados na ajuda do JSDoc), mas não são embutidos - que é o que eu estava procurando.
Studgeek
A pergunta é sobre a notação JSDoc embutida. Esta é uma informação interessante, mas não responde à pergunta
Ken Bellows
51

Eu encontrei uma maneira de fazer isso usando expressões do tipo Google Closure Compiler . Você coloca um sinal de igual após o tipo assim: function test(/**String=*/arg) {}

Studgeek
fonte
10
WebStorm / IntellIDEA suporta esta notação
Peter Aron Zentai
3
Sim, então acho que ganhou aceitação suficiente para marcá-la como a resposta.
studgeek
4
@PeterAronZentai, adicionarei WebStorm / IntelliIDEA que o suporta como resultado de eu ter feito uma solicitação de recurso para ele :). Eles agora suportam a maioria das expressões de tipo Google Closure Compiler, o que é excelente.
Studgeek
1
Não está funcionando para mim para um segundo parâmetro opcional.
DaveWalley
1
corrija o link; isso leva a uma página 404
chharvey,
3

Caso você esteja usando comentários do tipo embutido nos argumentos da função e esteja se perguntando como marcar um argumento da função como opcional nessa notação, descobri que apenas atribuir valores padrão aos argumentos opcionais funcionou. Se quiser que o padrão seja, undefinedvocê também deve defini-lo explicitamente, caso contrário, o argumento não será marcado como opcional (mesmo se for precedido por argumentos já opcionais):

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

Se você passar o mouse sobre demoseu IDE, deverá ver ambos optional1e optional2aparecendo como opcionais agora. Em VSCode, que é indicado por ?após o nome do argumento (notação TypeScript). Se você remover = undefinedde optional2, verá apenas optional1ser opcional, o que obviamente é um absurdo, então o valor padrão aqui deve ser explícito como eu aludi no parágrafo acima.

Tomáš Hübelbauer
fonte