记录中间功能可选参数

Document mid-function optional parameters

本文关键字：参数 功能 中间 记录      更新时间：2023-09-26

是否有适当的语法来记录可选的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，它（主要）使用谷歌闭包风格的文档。尽管我正在寻找一种更通用的最佳实践方法。

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

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

但这并没有像我希望的那样准确地描述情况。我希望，由于这已经成为一种常见的结构，有一些东西可以正确地处理它。

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

  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) {};

不幸的是，当使用三个参数时，无法指定需要一组类型，而当使用两个参数时则需要不同的类型。

使用闭包编译器jQuery-extens将为您提供大量示例。

相关文章：