tutorial returns ecmascript arguments ecmascript-6 jsdoc destructuring

arguments - ecmascript - jsdoc returns promise



Documentar parámetro de función desestructurado en JSDoc (2)

Ver JSDoc "Documentar las propiedades de un parámetro" :

/** * 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 comprobación de tipo de compilador de Google Closure , que se basó pero se desvió de JSDoc, también permite @param {{x:number,y:number}} point A "point-shaped" object. ) @param {{x:number,y:number}} point A "point-shaped" object.

Anteriormente siempre he documentado mis parámetros de objeto de la siguiente manera:

/** * 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 }

Pero no estoy seguro de cuál es el mejor enfoque con el parámetro de función desestructurado. ¿Simplemente ignoro el objeto, lo defino de alguna manera o cuál es la mejor manera de documentarlo?

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

Siento que mi enfoque anterior no hace obvio que la función espera un object y no dos parámetros diferentes.

Otra forma en que podría pensar sería utilizando @typedef , pero eso podría terminar siendo un gran desastre (especialmente en un archivo más grande con muchos métodos).

/** * @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 }


Así es como se pretende, en lo que puedo encontrar en el repositorio jsdoc3 :

/** * 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 }

Entonces, tu primer ejemplo es bastante correcto.

Otro ejemplo con un anidamiento más profundo:

/** * 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;