记录中间函数可选参数

Question

是否有适当的语法来记录可选的 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]
 */

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

Answer 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 会给你很多例子。