在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
}

我觉得我上面的方法没有清楚地表明该函数需要一个object参数而不是两个不同的参数。

另一种想法是使用@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
}

- morkro

---

我认为第一种方法仍然不错。没有人在乎你的代码中对象是否命名为 config 或者根本没有任何名称。 - Bergi

在WebStorm中，我发现如果我只描述（解构后的）参数并忽略解构，它大多数情况下都能正常工作，除了一些不太常见的情况。因此，在您的示例中，描述两个参数foo和bar。这不是最终解决方案，但使用对象的任何方法都会产生检查错误 - 而IDE的检查和自动完成是我最关心的。 - Mörre

Answer 1

这就是预期的方式，如文档中所描述的。

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

- Cerbrus

---

@ZachB：function ({a}, {a}) {}是无效的语法，因为a在那里被定义了两次。 - Cerbrus

糟糕。({a: b}, {a}))或({a}, {b}) - 关键点是JSDoc @param标签是无序的，而且如果JSDoc尝试使用属性名称进行匹配，则键可能会产生歧义。下一个版本的VSCode将使用位置查找来解决这种情况。 - ZachB

使用这个代码，我得到了eslint警告：“缺少'param'参数的JSDoc参数描述。”（valid-jsdoc） - Jean Paul

@jjmerelo 不好意思，那是个打错字。 - Cerbrus

原来VSCode和其他编辑器（仍然）不完全支持这种语法：参数描述未显示。 - undefined

Answer 2

我个人使用的是这个：

/**
* @param {{
  a: number
  b: number
}} param0
* @returns {number} The sum
*/
const func = ({ a, b }) => a + b;

就在那里创建对象。

我也利用TypeScript，并且会将可选的b声明为b?或b: number | undefined，因为JSDoc也允许联合类型

- Coding Edgar

---

对于多个参数，只需添加名称（不使用任何类型）。const letters = (d, {a, b: {c}}) => a + c; 添加[at]param {number} d或[at]param d以不覆盖类型。 - Damien Golding

Answer 3

请参阅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) {
    // ...
};

(Google Closure 编译器类型检查，它基于但与 JSDoc 不同，还允许 @param {{x:number,y:number}} point A "point-shaped" object.)

- Jakub Holý

---

您IP地址为143.198.54.68，由于运营成本限制，当前对于免费用户的使用频率限制为每个IP每72小时10次对话，如需解除限制，请点击左下角设置图标按钮（手机用户先点击左上角菜单按钮）。 - Bergi

这个回答没有解答问题——这个例子没有使用解构！使用解构时，你没有父级对象。 - Mörre

实际上，在他的示例之后，他给出了一个相对应的示例，其中包含完全相同的jsdoc注释，用于Project.prototype.assign = function({ name, department })。在示例之前，他们说：“如果没有明确的名称对参数进行解构，则可以为对象指定适当的名称并记录其属性。” - notacouch