Até agora, existem 4 maneiras diferentes de documentar objetos como parâmetros / tipos. Cada um tem seus próprios usos. Apenas 3 deles podem ser usados para documentar valores retornados.
Para objetos com um conjunto conhecido de propriedades (Variante A)
/**
* @param {{a: number, b: string, c}} myObj description
*/
Essa sintaxe é ideal para objetos que são usados apenas como parâmetros para esta função e não exigem descrição adicional de cada propriedade. Ele pode ser usado para @returns
bem .
Para objetos com um conjunto conhecido de propriedades (Variante B)
Muito úteis são os parâmetros com sintaxe de propriedades :
/**
* @param {Object} myObj description
* @param {number} myObj.a description
* @param {string} myObj.b description
* @param {} myObj.c description
*/
Essa sintaxe é ideal para objetos que são usados apenas como parâmetros para esta função e que exigem descrição adicional de cada propriedade. Isso não pode ser usado para @returns
.
Para objetos que serão usados em mais de um ponto na origem
Nesse caso, um @typedef é muito útil. Você pode definir o tipo em um ponto da sua origem e usá-lo como um tipo para @param
ou @returns
ou outras tags JSDoc que podem fazer uso de um tipo.
/**
* @typedef {Object} Person
* @property {string} name how the person is called
* @property {number} age how many years the person lived
*/
Você pode usar isso em uma @param
tag:
/**
* @param {Person} p - Description of p
*/
Ou em um @returns
:
/**
* @returns {Person} Description
*/
Para objetos cujos valores são todos do mesmo tipo
/**
* @param {Object.<string, number>} dict
*/
O primeiro tipo (string) documenta o tipo de chave que no JavaScript sempre é uma string ou, pelo menos, sempre será coagida a uma string. O segundo tipo (número) é o tipo do valor; isso pode ser de qualquer tipo. Essa sintaxe também pode ser usada @returns
.
Recursos
Informações úteis sobre os tipos de documentação podem ser encontradas aqui:
https://jsdoc.app/tags-type.html
PS:
para documentar um valor opcional, você pode usar []
:
/**
* @param {number} [opt_number] this number is optional
*/
ou:
/**
* @param {number|undefined} opt_number this number is optional
*/