Comment spécifier un tableau d'objets comme paramètre ou valeur de retour dans JSDoc?

105

Dans JSDoc, la meilleure documentation que je peux trouver montre l'utilisation de ce qui suit si vous avez un tableau d'un type spécifique (tel qu'un tableau de chaînes) comme:

/**
 * @param {Array.<string>} myStrings All my awesome strings
 */
 function blah(myStrings){
     //stuff here...
 }

Comment remplaceriez-vous les points d'interrogation ci-dessous pour spécifier un tableau d'objets?

/**
 * @param {???????} myObjects All of my equally awesome objects
 */
 function blah(myObjects){
     //stuff here...
 }
Rayon
la source
5
duplication possible de la valeur et du paramètre de retour
Gajus

Réponses:

180

Vous devriez être plus précis ce que vous entendez par JSDoc - il s'agit d'un terme générique couvrant à peu près tous les outils de documentation de style JavaDoc pour JavaScript.

La syntaxe que vous avez utilisée pour le tableau de chaînes ressemble à celle prise en charge par Google Closure Compiler .

En utilisant cela, un tableau d'objets serait:

/**
 * @param {Array.<Object>} myObjects
 */

Ou juste un tableau de tout - cela devrait fonctionner avec à peu près tous les outils de documentation:

/**
 * @param {Array} myArray
 */

jsdoc-toolkit , JSDoc 3 et JSDuck prennent en charge la syntaxe suivante pour désigner un tableau d'objets:

/**
 * @param {Object[]} myArray
 */

ÉDITER

Si vous connaissez les clés et le type de variable des valeurs, vous pouvez également faire:

/**
 * @param {Array.<{myNumber: Number, myString: String, myArray: Array}>} myObjects
 */

ou

/**
 * @param {{myNumber: Number, myString: String, myArray: Array}[]} myObjects
 */
René Saarsoo
la source
10
Le . la notation est désormais obsolète et son support devrait être abandonné plus tard. La version correcte actuelle est {Array<Object>}. Juste pour garder ce message à jour.
Kenny806
2
Avec JSDoc 3, comment documenteriez-vous un tableau de tableaux String? Dans l'ancienne syntaxe, je pourrais faire quelque chose commeArray.<string[]>
Snekse
9
@ Kenny806 Obsolète? Un document de référence s'il vous plaît?
Wilt
2
@Wilt: la documentation JSDoc est contradictoire sur le point avant les chevrons.
Dan Dascalescu
2
Cette réponse n'explique pas comment déclarer les clés des objets de ce tableau et comment déclarer un tableau d'objets avec des clés spécifiques comme type de retour. Cette réponse le fait.
Dan Dascalescu