web-dev-qa-db-fra.com

Documenter le paramètre de fonction déstructurée dans JSDoc

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ée. Dois-je simplement ignorer l'objet, le définir en quelque sorte 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 rend pas évident que la fonction attend un object et non deux paramètres différents.

Une autre façon de penser serait d'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
}
argumentsecmascript-6jsdocdestructuring
46
morkro

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;
41
Cerbrus