Documento parametro di funzione destrutturato in JSDoc

Question

In precedenza ho sempre documentato i miei parametri degli oggetti come segue:

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

Ma io sono sicuro che cosa l'approccio migliore è con il parametro di funzione desctructured. Devo semplicemente ignorare l'oggetto, definirlo in qualche modo o qual è il modo migliore per 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 
} 

mi sento come il mio approccio di cui sopra non lo rende evidente che la funzione si aspetta un parametro diverso object e non due.

Un altro modo che potrei pensare sarebbe utilizzare @typedef, ma questo potrebbe finire per essere un disastro enorme (specialmente in un file più grande con molti metodi)?

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

Answer 1

Vedi JSDoc's "Documenting a parameter's properties":

/** 
* 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) { 
    // ... 
}; 

(Google Closure compiler type checking, che si basa su, ma deviato da JSDoc, permette anche @param {{x:number,y:number}} point A "point-shaped" object.)

Answer 2

Questo è come è inteso, per quanto posso trovare su il jsdoc3 repo:

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

Quindi, il tuo primo esempio è praticamente corretto.

Un altro esempio con un po 'più in profondità di nidificazione:

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