文档中间函数可选参数

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 闭包样式（主要）。虽然我正在寻找更通用的最佳实践方法。

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

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

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

Answer 1

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

Javascript 并不真正支持函数参数列表中间的可选参数（为此您需要命名参数）。相反，宣传此功能的函数会尝试根据参数的数量和值来辨别调用了哪个版本的函数。
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 会给你很多例子。

文档中间函数可选参数

Document mid-function optional parameters

javascript

google-closure

jsdoc

jsdoc3