Document paramètre de fonction déstructurée dans JSDoc

89

Auparavant, j'ai toujours documenté mes paramètres d'objet comme suit:

/**
 * Description of the function
 *
 * @param {Object} config - The configuration
 * @param {String} config.foo
 * @param {Boolean} [config.bar] - Optional value
 * @return {String}
 */
function doSomething (config = {}) {
  const { foo, bar } = config;
  console.log(foo, bar);
  // do something
}

Mais je ne sais pas quelle est la meilleure approche avec le paramètre de fonction déstructuré. Dois-je simplement ignorer l'objet, le définir d'une manière ou d'une autre ou quelle est la meilleure façon de le documenter?

/**
 * Description of the function
 *
 * @param {String} foo
 * @param {Boolean} [bar] - Optional value
 * @return {String}
 */
function doSomething ({ foo, bar } = {}) {
  console.log(foo, bar);
  // do something
}

J'ai l'impression que mon approche ci-dessus ne montre pas clairement que la fonction attend un objectparamètre différent et non deux.

Une autre façon de penser serait de l'utiliser @typedef, mais cela pourrait finir par être un énorme gâchis (en particulier dans un fichier plus volumineux avec de nombreuses méthodes)?

/**
 * @typedef {Object} doSomethingConfiguration
 * @property {String} foo
 * @property {Boolean} [bar] - Optional value
 */

/**
 * Description of the function
 *
 * @param {doSomethingConfiguration}
 * @return {String}
 */
function doSomething ({ foo, bar } = {}) {
  console.log(foo, bar);
  // do something
}
morkro
la source
1
Je pense que la première approche est toujours bonne. Personne ne se soucie de savoir si l'objet est nommé configdans votre code ou s'il a un nom du tout.
Bergi
Dans WebStorm, j'ai trouvé que si je décris simplement les paramètres (après la déstructuration) et ignore la déstructuration, cela fonctionne principalement, sauf dans les cas moins courants. Donc, dans votre exemple, décrivez deux paramètres fooet bar. Ce n'est pas une solution finale, mais toute approche utilisant un objet a généré des erreurs d'inspection - et les inspections et les autocomplétions de l'EDI sont ce qui m'importe le plus.
Mörre le

Réponses:

96

C'est ainsi que cela est prévu, comme décrit dans la documentation .

/**
 * My cool function.
 *
 * @param {Object} obj - An object.
 * @param {string} obj.prop1 - Property 1.
 * @param {string} obj.prop2 - Property 2.
 */
var fn = function ({prop1, prop2}) {
  // Do something with prop1 and prop2
}

Donc, votre premier exemple est à peu près correct.

Un autre exemple avec une imbrication plus profonde:

/**
 * Nesting example.
 *
 * @param {object} param
 * @param {number} param.a - First value
 * @param {object} param.b - Wrapper
 * @param {number} param.b.c - Second value
 * @return {number} sum a and b
 */
letters = ({a, b: {c}}) => a + c;
Cerbrus
la source
Je ne vois pas comment JSDoc fonctionne sans ambiguïté lorsque vous avez plusieurs arguments déstructurés, comme function ({a}, {a}) {}. Le JSDoc, je suppose, serait @param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.a, et s'appuie sur la commande des @parambalises?
ZachB
@ZachB: function ({a}, {a}) {}est une syntaxe invalide, car elle aest définie deux fois, là.
Cerbrus
1
Oups. ({a: b}, {a}))ou ({a}, {b})- le fait est que les @parambalises JSDoc sont AFAIK sans ordre et que les clés peuvent être ambiguës si JSDoc essaie de faire correspondre en utilisant des noms de propriétés. La prochaine version de VSCode va utiliser la recherche positionnelle pour résoudre ce scénario.
ZachB
1
Merci, @ d0gb3r7. J'ai mis à jour le lien dans la réponse.
Cerbrus
-8

Voir "Documenter les propriétés d'un paramètre" de JSDoc :

/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function(employee) {
    // ...
};

( La vérification du type du compilateur Google Closure , qui était basée sur JSDoc mais détournée de JSDoc, permet également @param {{x:number,y:number}} point A "point-shaped" object.)

Jakub Holý
la source
2
N'est-il pas déjà en train de le faire? Il demande ce qu'il faut faire maintenant qu'il n'y a plus de employeevariable dans la fonction.
Bergi
7
Cela ne répond pas à la question - cet exemple n'utilise pas de déstructuration! Avec la déstructuration, vous n'avez aucun objet parent.
Mörre le
En fait, son même lien, juste après son exemple, donne un exemple relatif avec les mêmes commentaires jsdoc exacts pour Project.prototype.assign = function({ name, department }). Avant l'exemple, ils disent: "Si un paramètre est déstructuré sans nom explicite, vous pouvez donner à l'objet un nom approprié et documenter ses propriétés."
notacouch