0

是否有用于记录可选 JavaScript 参数的正确语法，其中可选参数位于函数头的中间（想想 jQuery、Gulp 等）

我已经以标准方式记录了该功能，并且效果很好。问题是当我尝试将第二个参数设置为最后一个变量时（在未使用可选参数的情况下），我的 IDE 会感到困惑。

例子：

/**
 * @param {number} a_num
 * @param {string} [a_str='']
 * @param {{}} a_obj
 */
function (a_num, a_str, a_obj) {
    if (!a_obj) a_obj = a_str; // doesn't want me to save a string to an object.
    a_str = '';
    // more stuff
}

如果重要的话，我正在使用 JetBrains 的 PHPStorm，它主要使用 Google Closure 文档样式。虽然我正在寻找一种更通用的最佳实践方法。

我怀疑我可以做一些丑陋的事情，比如：

/**
 * @param {number} a_num
 * @param {string|{}} a_str
 * @param {{}} [a_obj=null]
 */

但这并不能像我想的那样准确地描述这种情况。我希望因为这正在成为一种常见的结构，所以有一些东西可以正确处理它。

4

1 回答 1

1

在函数的参数列表中间注释可选参数几乎与维护使用这种类型的方法签名的代码一样具有挑战性。

  1. Javascript 并不真正支持函数参数列表中间的可选参数（为此，您需要命名参数）。相反，宣传这一点的函数会尝试根据参数的数量和值来辨别调用了哪个版本的函数。

  2. Javascript 也不支持函数重载。

认识到这些限制为支持本质上是文档策略的内容提供了第一条线索。您的注释必须支持所有类型的调用——这样做会在使用强制或检查类型的工具时失去一定的类型安全性。

让我们以其中一个jQuery.prototype.bind签名为例：

jQuery.prototype.bind( eventType [, eventData ], handler )

为了记录此方法，我们认识到始终需要两个参数。首先让我们重新排列和重命名参数：

jQuery.prototype.bind( eventType, eventDataOrHandler, [ handler ] )

通过这种重新排列，JSDoc 变得更加清晰：

/**
 * @param {string} eventType
 * @param {(*|function(Event))} eventDataOrHandler
 * @param {function(Event)=} handler
 * @return {!jQuery}
 */
jQuery.prototype.bind =
    function(eventType, eventDataOrHandler, handler) {};

不幸的是，没有办法指定当使用三个参数时需要一组类型，而当使用两个参数时需要另一组类型。

仔细阅读 Closure-compiler jQuery externs会给你很多例子。

于 2015-02-12T14:38:35.840 回答