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;