javascript - 如何记录具有已知参数类型的可变长度的参数列表？

Question

相关:Correct way to document open-ended argument functions in JSDoc

我有一个函数，它通过访问 arguments 变量接受多个数组:

/**
 * @param options An object containing options
 * @param [options.bind] blablabla (optional)
 */
function modify_function (options) {
    for (var i=1; i<arguments.length; i++) {
        // ...
    }
}

现在，我知道除了 options 之外的每个参数都是一个包含值得记录的值的数组:

[search_term, replacement, options]

我不考虑将(冗长的)描述放在可变参数行中。

@param {...} An array with search terms, replacements and its options; index 0: the search term within the function; 1: the replacement text; 2: optional options (catch_errors: catches errors and log it, escape: escape dollars in the replacement text, pos: "L" for placing the replacement before the search term, "R" for placing it after) Not a readable solution and the type is not visible.

有没有办法记录可变参数的类型和值？

@param {...[]} An array with search terms, replacements and its options
@param {...[0]} The search term within the function
@param {...[1]} The replacement text 
@param {...[2]} An optional object with obtions for the replacement
@param {...[2].catch_errors} catches errors and log it
@param {...[2].escape} etc...

上面看起来很丑陋，但它应该让您了解我正在努力实现的目标:

• 记录可变参数的类型(在本例中为数组)
• 记录这个数组的值
• 记录此数组中对象的属性

为了懒惰，我使用了数组而不是对象。随时欢迎其他建议。

Answer 1

您的函数不是真正的可变参数，您应该将其签名更改为 foundrama 建议的内容。除了 JSDoc 的语法比 foundrama 建议的好一点

/**
 * @param {String} searchTerm
 * @param {String} replacementText
 * @param {Object} opts (optional) An object containing the replacement options
 * @param {Function} opts.catch_errors Description text
 * @param {Event} opts.catch_errors.e The name of the first parameter 
 *         passed to catch_errors
 * @param {Type} opts.escape Description of options
 */

你会这样调用它

modify_text('search', 'replacement', {
    catch_errors: function(e) {

    },
    escape: 'someEscape'

});

如果你真的有 varargs 风格的案例，它应该是一个相同类型的变量，可以在参数列表的末尾传递，我像下面这样记录它，虽然它不是 JSDoc 标准，它是Google 在他们的文档中使用了什么

/**
 * Sums its parameters
 * @param {...number} var_args Numbers to be added together
 * @return number
 */
function sum(/* num, num, ... */) { 
    var sum = 0;
    for (var i =0; i < arguments.length; i++) {
      sum += arguments[i];
    }
    return sum;
}