Parâmetro de função desestruturada de documento em JSDoc


90

Anteriormente, sempre documentei meus parâmetros de objeto da seguinte maneira:

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

Mas não tenho certeza de qual é a melhor abordagem com o parâmetro de função desestruturada. Devo apenas ignorar o objeto, defini-lo de alguma forma ou qual é a melhor maneira de documentá-lo?

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

Acho que minha abordagem acima não deixa óbvio que a função espera um objecte não dois parâmetros diferentes.

Outra maneira que eu poderia imaginar seria usando @typedef, mas isso pode acabar sendo uma grande bagunça (especialmente em um arquivo maior com muitos 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
}

1
Acho que a primeira abordagem ainda está bem. Ninguém se importa se o objeto é nomeado configem seu código ou se tem algum nome.
Bergi

No WebStorm, descobri que, se eu apenas descrever os parâmetros (após a desestruturação) e ignorar a desestruturação, a maioria das vezes funciona, exceto em casos menos comuns. Portanto, em seu exemplo, descreva dois parâmetros fooe bar. Não é uma solução final, mas qualquer abordagem usando um objeto gerou erros de inspeção - e inspeções e preenchimentos automáticos do IDE é o que mais me preocupa.
Mörre

Respostas:


96

É assim que se pretende, conforme descrito na documentação .

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

Portanto, seu primeiro exemplo está bastante correto.

Outro exemplo com alguns aninhamentos mais profundos:

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

Não vejo como o JSDoc funciona sem ambigüidades quando você tem vários argumentos desestruturados, como function ({a}, {a}) {}. O JSDoc eu acho que seria @param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.a, e confio na ordem das @paramtags?
ZachB

@ZachB: function ({a}, {a}) {}é uma sintaxe inválida, pois aé definida duas vezes aqui.
Cerbrus

1
Ops. ({a: b}, {a}))ou ({a}, {b})- o ponto era que as @paramtags JSDoc são AFAIK sem ordem e as chaves podem ser ambíguas se o JSDoc tentar fazer a correspondência usando nomes de propriedade. A próxima versão do VSCode usará pesquisa posicional para resolver esse cenário.
ZachB

1
Obrigado, @ d0gb3r7. Eu atualizei o link na resposta.
Cerbrus


-8

Consulte "Documentando as propriedades de um parâmetro" do 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) {
    // ...
};

(A verificação de tipo de compilador do Google Closure , que foi baseada em, mas desviada do JSDoc, também permite @param {{x:number,y:number}} point A "point-shaped" object.)


2
Ele já não está fazendo isso? Ele está perguntando o que fazer agora que não há mais nenhuma employeevariável na função.
Bergi

7
Isso não responde à pergunta - este exemplo não usa desestruturação! Com a desestruturação, você não tem nenhum objeto pai.
Mörre

Na verdade, seu mesmo link, logo após seu exemplo, dá um exemplo relativo com os mesmos comentários de jsdoc exatos para Project.prototype.assign = function({ name, department }). Antes do exemplo, eles dizem: "Se um parâmetro for desestruturado sem um nome explícito, você pode dar ao objeto um nome apropriado e documentar suas propriedades."
notacouch
Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.