Ormai ci sono 4 modi diversi per documentare gli oggetti come parametri / tipi. Ognuno ha i suoi usi. Tuttavia, solo 3 di questi possono essere utilizzati per documentare i valori restituiti.
Per oggetti con un set di proprietà noto (variante A)
/**
* @param {{a: number, b: string, c}} myObj description
*/
Questa sintassi è ideale per gli oggetti che vengono utilizzati solo come parametri per questa funzione e non richiedono un'ulteriore descrizione di ciascuna proprietà. Esso può essere utilizzato per @returns
pure .
Per oggetti con un set di proprietà noto (variante B)
Molto utili sono i parametri con sintassi delle proprietà :
/**
* @param {Object} myObj description
* @param {number} myObj.a description
* @param {string} myObj.b description
* @param {} myObj.c description
*/
Questa sintassi è ideale per gli oggetti che vengono utilizzati solo come parametri per questa funzione e che richiedono un'ulteriore descrizione di ciascuna proprietà. Questo non può essere usato per @returns
.
Per oggetti che verranno utilizzati in più di un punto nell'origine
In questo caso un @typedef è molto utile. È possibile definire il tipo ad un certo punto nella vostra sorgente e utilizzarlo come un tipo per @param
o @returns
o altri tag JSDoc che possono fare uso di un tipo.
/**
* @typedef {Object} Person
* @property {string} name how the person is called
* @property {number} age how many years the person lived
*/
È quindi possibile utilizzare questo in un @param
tag:
/**
* @param {Person} p - Description of p
*/
O in un @returns
:
/**
* @returns {Person} Description
*/
Per oggetti i cui valori sono tutti dello stesso tipo
/**
* @param {Object.<string, number>} dict
*/
Il primo tipo (stringa) documenta il tipo di chiavi che in JavaScript è sempre una stringa o almeno sarà sempre costretta a una stringa. Il secondo tipo (numero) è il tipo del valore; questo può essere di qualsiasi tipo. Anche questa sintassi può essere utilizzata @returns
.
risorse
Informazioni utili sui tipi di documentazione sono disponibili qui:
https://jsdoc.app/tags-type.html
PS:
per documentare un valore opzionale è possibile utilizzare []
:
/**
* @param {number} [opt_number] this number is optional
*/
o:
/**
* @param {number|undefined} opt_number this number is optional
*/