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

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

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将为您提供大量示例。

记录中间功能可选参数

1 个答案: