arguments - 在 JSDoc 中记录解构函数参数

Question

以前我总是按如下方式记录我的对象参数:

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

但我不确定使用解构函数参数的最佳方法是什么。我是否只是忽略该对象，以某种方式定义它或者记录它的最佳方式是什么？

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

我觉得我上面的方法并没有明显表明该函数需要一个对象而不是两个不同的参数。

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

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

这就是它的意图，如 documentation 中所述。 .

/**
 * My cool function.
 *
 * @param {Object} obj - An object.
 * @param {string} obj.prop1 - Property 1.
 * @param {string} obj.prop2 - Property 2.
 */
const fn = function ({prop1, prop2}) {
  // Do something with prop1 and prop2
}

所以，你的第一个例子非常正确。

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

/**
 * 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
 */
const letters = ({a, b: {c}}) => a + c;