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

Question

相关:在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 {...}包含搜索词,替换词及其选项的数组; index 0:函数内的搜索项; 1:替换文字; 2:可选选项(catch_errors:捕获错误并记录它,escape:替换文本中的escape美元,pos:"L"用于在搜索项之前放置替换,"R"用于放置它之后)不是可读解决方案类型不可见.

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

@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...

以上看起来很难看,但它应该让你知道我想要实现的目标:

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

对于懒惰,我使用了数组而不是对象.其他建议随时欢迎.

Answer 1

你的函数不是真正可变的参数,你应该将它的签名改为findrama建议的内容.除了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;
}