JSDoc中的文档解构函数参数 [英] Document destructured function parameter in JSDoc

问题描述

以前，我总是将我的对象参数记录如下:

Previously I've always documented my object parameters as follows:

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

但是我不确定使用分散的函数参数最好的方法是什么.我只是忽略对象，以某种方式定义它还是记录它的最佳方法是什么?

But I am unsure what the best approach is with desctructured function parameter. Do I just ignore the object, define it somehow or what is the best way of documenting it?

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

我感觉上面的方法并不能很明显地表明该函数需要一个object而不是两个不同的参数.

I feel like my approach above doesn't make it obvious that the function expects an object and not two different parameter.

我可以想到的另一种方法是使用@typedef，但这最终可能会变成一团糟(尤其是在具有许多方法的较大文件中)?

Another way I could think of would be using @typedef, but that might end up being a huge mess (especially in a larger file with many methods)?

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

推荐答案

如文档.

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

因此，您的第一个示例非常正确.

So, your first example is pretty much correct.

另一个具有更深层嵌套的示例:

Another example with some deeper nesting:

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

这篇关于JSDoc中的文档解构函数参数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！