Por ahora hay 4 formas diferentes de documentar objetos como parámetros / tipos. Cada uno tiene sus propios usos. Sin embargo, solo 3 de ellos se pueden usar para documentar valores de retorno.
Para objetos con un conjunto conocido de propiedades (Variante A)
/**
* @param {{a: number, b: string, c}} myObj description
*/
Esta sintaxis es ideal para objetos que se usan solo como parámetros para esta función y no requieren una descripción más detallada de cada propiedad. Se puede utilizar para @returns
así .
Para objetos con un conjunto conocido de propiedades (Variante B)
Muy útiles son los parámetros con sintaxis de propiedades :
/**
* @param {Object} myObj description
* @param {number} myObj.a description
* @param {string} myObj.b description
* @param {} myObj.c description
*/
Esta sintaxis es ideal para objetos que se usan solo como parámetros para esta función y que requieren una descripción más detallada de cada propiedad. Esto no se puede usar para @returns
.
Para objetos que se usarán en más de un punto en la fuente
En este caso, un @typedef es muy útil. Se puede definir el tipo en un momento de su fuente y utilizarlo como un tipo de @param
u @returns
u otras etiquetas jsdoc que pueden hacer uso de un tipo.
/**
* @typedef {Object} Person
* @property {string} name how the person is called
* @property {number} age how many years the person lived
*/
Luego puede usar esto en una @param
etiqueta:
/**
* @param {Person} p - Description of p
*/
O en un @returns
:
/**
* @returns {Person} Description
*/
Para objetos cuyos valores son todos del mismo tipo
/**
* @param {Object.<string, number>} dict
*/
El primer tipo (cadena) documenta el tipo de las claves que en JavaScript siempre es una cadena o al menos siempre se coaccionará a una cadena. El segundo tipo (número) es el tipo del valor; Esto puede ser de cualquier tipo. Esta sintaxis también se puede utilizar @returns
.
Recursos
Puede encontrar información útil sobre los tipos de documentación aquí:
https://jsdoc.app/tags-type.html
PD:
para documentar un valor opcional que puede usar []
:
/**
* @param {number} [opt_number] this number is optional
*/
o:
/**
* @param {number|undefined} opt_number this number is optional
*/