JSDoc中的文档解构函数参数

Posted 2023-02-22

【中文标题】JSDoc中的文档解构函数参数

【英文标题】：Document destructured function parameter in JSDoc

【发布时间】：2016-08-23 08:13:57

【问题描述】：

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

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

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

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

【问题讨论】：

我认为第一种方法还是可以的。没有人关心对象在您的代码中是否命名为 config 或是否有任何名称。

在 WebStorm 中，我发现如果我只描述（解构后）参数而忽略解构，除了不太常见的情况外，它大部分都有效。所以在你的例子中，描述两个参数foo 和bar。这不是最终解决方案，但任何使用对象的方法都会产生检查错误——我最关心的是来自 IDE 的检查和自动完成。

【参考方案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;

【讨论】：

当您有多个解构参数（如function (a, a) ）时，我看不出 JSDoc 是如何明确工作的。我猜的 JSDoc 是@param object param1, @param * param1.a, @param object param2, @param * param2.a，并且依赖于@param 标签的排序？

@ZachB: function (a, a) 是无效的语法，因为a 在那里定义了两次。

糟糕。 (a: b, a)) 或 (a, b) -- 关键是 JSDoc @param 标签是无序的 AFAIK，如果 JSDoc 尝试使用属性名称进行匹配，键可能会模棱两可。下一版本的 VSCode 将使用位置查找来解决这种情况。

谢谢，@d0gb3r7。我已经更新了答案中的链接。

这样我得到了 eslint 警告：“缺少 'param' 的 JSDoc 参数描述。” (有效的jsdoc)

【参考方案2】：

我个人用这个：

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

只需在此处创建对象即可。

I also take advantage of TypeScript，并将可选的b 声明为b? 或b: number | undefined 作为JSDoc also allows unions

【参考方案3】：

见JSDoc's "Documenting a parameter's properties"：

/**
 * 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 compiler type checking，基于但转自JSDoc，也允许@param x:number,y:number point A "point-shaped" object.)

【讨论】：

他不是已经这样做了吗？他问现在函数中没有employee 变量该怎么办。

这不能回答问题——这个例子不使用解构！解构你没有父对象。

实际上是他的相同链接，就在他的示例给出了一个相对示例之后，该示例具有与Project.prototype.assign = function( name, department ) 完全相同的 jsdoc cmets。在示例之前，他们说：“如果参数在没有明确名称的情况下被解构，您可以给对象一个适当的名称并记录其属性。”