Documentare il parametro della funzione destrutturata in JSDoc


90

In precedenza ho sempre documentato i parametri dei miei 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 non sono sicuro di quale sia l'approccio migliore con il parametro della funzione destrutturato. Ignoro l'oggetto, lo definisco 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 sembra che il mio approccio sopra non renda ovvio che la funzione si aspetta un objectparametro diverso e non due.

Un altro modo a cui potrei pensare sarebbe quello di usare @typedef, ma potrebbe finire per essere un enorme pasticcio (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
}

1
Penso che il primo approccio vada ancora bene. A nessuno importa se l'oggetto è nominato confignel tuo codice o se ha un nome.
Bergi

In WebStorm ho scoperto che se descrivo solo i parametri (dopo la destrutturazione) e ignoro la destrutturazione, per lo più funziona tranne per i casi meno comuni. Quindi, nel tuo esempio, descrivi due parametri fooe bar. Non è una soluzione finale, ma qualsiasi approccio che utilizza un oggetto ha prodotto errori di ispezione e le ispezioni e i completamenti automatici dall'IDE sono ciò a cui tengo di più.
Mörre

Risposte:


96

Ecco come è inteso, come descritto nella documentazione .

/**
 * 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 una nidificazione più profonda:

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

Non vedo come funziona JSDoc in modo inequivocabile quando hai più argomenti destrutturati, come function ({a}, {a}) {}. Il JSDoc immagino sarebbe @param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.a, e fare affidamento sull'ordinamento dei @paramtag?
ZachB

@ZachB: function ({a}, {a}) {}non è una sintassi non valida, poiché aè definita due volte, lì.
Cerbrus

1
Ops. ({a: b}, {a}))oppure ({a}, {b})- il punto era che i @paramtag JSDoc sono privi di ordine AFAIK e le chiavi possono essere ambigue se JSDoc cerca di abbinare usando nomi di proprietà. La prossima versione di VSCode utilizzerà la ricerca di posizione per risolvere questo scenario.
ZachB

1
Grazie, @ d0gb3r7. Ho aggiornato il link nella risposta.
Cerbrus


-8

Vedere "Documentazione delle proprietà di un parametro" di JSDoc :

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

(Il controllo del tipo del compilatore di Google Closure , basato su JSDoc ma deviato da JSDoc, consente anche @param {{x:number,y:number}} point A "point-shaped" object.)


2
Non lo sta già facendo? Chiede cosa fare ora che non ci sono più employeevariabili nella funzione.
Bergi

7
Questo non risponde alla domanda: questo esempio non utilizza la destrutturazione! Con la destrutturazione non hai alcun oggetto genitore.
Mörre,

In realtà il suo stesso collegamento, subito dopo il suo esempio, fornisce un esempio relativo con gli stessi esatti commenti jsdoc per Project.prototype.assign = function({ name, department }). Prima dell'esempio si dice: "Se un parametro viene destrutturato senza un nome esplicito, è possibile assegnare all'oggetto uno appropriato e documentarne le proprietà".
notacouch
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.