Parámetro de función de documento desestructurado en JSDoc

89

Anteriormente, siempre he documentado los parámetros de mis objetos 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 descestructurado. ¿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 que sea obvio que la función espera un objectparámetro diferente y no dos.

Otra forma en la que podría pensar sería usar @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
}
morkro
fuente
1
Creo que el primer enfoque todavía está bien. A nadie le importa si el objeto tiene un nombre configen su código o si tiene algún nombre.
Bergi
En WebStorm he descubierto que si solo describo los parámetros (después de la desestructuración) e ignoro la desestructuración, la mayoría de las veces funciona, excepto en casos menos comunes. Entonces, en su ejemplo, describa dos parámetros fooy bar. No es una solución final, pero cualquier enfoque que utilice un objeto produjo errores de inspección, y las inspecciones y las autocompletadas del IDE es lo que más me importa.
Mörre

Respuestas:

96

Así es como está previsto, como se describe en la documentación .

/**
 * 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, su 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;
Cerbrus
fuente
No veo cómo JSDoc funciona de manera inequívoca cuando tiene múltiples argumentos desestructurados, como function ({a}, {a}) {}. ¿El JSDoc supongo que sería @param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.a, y dependería del orden de las @parametiquetas?
ZachB
@ZachB: function ({a}, {a}) {}es una sintaxis inválida, ya que ase define dos veces, allí.
Cerbrus
1
¡Ups! ({a: b}, {a}))o ({a}, {b})- el punto fue que las @parametiquetas JSDoc son AFAIK sin orden y las claves pueden ser ambiguas si JSDoc intenta hacer coincidir usando nombres de propiedad. La próxima versión de VSCode utilizará la búsqueda posicional para resolver este escenario.
ZachB
1
Gracias, @ d0gb3r7. Actualicé el enlace en la respuesta.
Cerbrus
-8

Consulte "Documentación de las propiedades de un parámetro" de 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) {
    // ...
};

(La verificación de tipo del compilador de cierre de Google , que se basó en JSDoc pero se desvió de él, también permite @param {{x:number,y:number}} point A "point-shaped" object.)

Jakub Holý
fuente
2
¿No está ya haciendo eso? Pregunta qué hacer ahora que ya no hay ninguna employeevariable en la función.
Bergi
7
Esto no responde a la pregunta: ¡este ejemplo no usa la desestructuración! Con la desestructuración no tienes un objeto principal.
Mörre
En realidad, su mismo enlace, justo después de su ejemplo, da un ejemplo relativo con los mismos comentarios jsdoc exactos para Project.prototype.assign = function({ name, department }). Antes del ejemplo, dicen: "Si un parámetro se desestructura sin un nombre explícito, puede darle al objeto uno apropiado y documentar sus propiedades".
notacouch