Dokument destructured Funktionsparameter in JSDoc

Question

Früher habe ich immer meine Objektparameter wie folgt dokumentiert:

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

Aber ich bin nicht sicher, was der beste Ansatz mit desctructured Funktionsparameter ist. Ignoriere ich das Objekt einfach, definiere es irgendwie oder wie dokumentiere ich es am besten?

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

Ich fühle mich wie mein Ansatz oben macht es nicht offensichtlich, dass die Funktion erwartet eine object und nicht zwei verschiedene Parameter.

Eine andere Möglichkeit, die ich mir vorstellen könnte, würde @typedef verwenden, aber das könnte am Ende eine riesige Sauerei sein (besonders in einer größeren Datei mit vielen Methoden)?

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

Siehe 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, dass stützte sich auf, aber von JSDoc abgelenkt, ermöglicht auch @param {{x:number,y:number}} point A "point-shaped" object.)

Answer 2

Dies ist, wie es beabsichtigt ist, soweit ich auf finden die 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 
} 

Also, dein erstes Beispiel ist ziemlich korrekt.

Ein anderes Beispiel mit etwas tiefer Verschachtelung:

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