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

问题描述

| 相关：在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++) {
        // ...
    }
}

现在，我知道除ѭ2之外的每个参数都是一个数组，其中包含值得记录的值：

[search_term,replacement,options]

我不考虑将（冗长的）描述放在可变参数行中。   @param {...}包含搜索项，替换项及其选项的数组；索引0：函数内的搜索词； 1：替换文字； 2：可选选项（catch_errors：捕获错误并将其记录，转义：在替换文本中转义美元，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...

上面的代码看起来很丑陋，但是应该可以让您大致了解我要实现的目标： 记录变量参数的类型（在这种情况下为数组） 记录此数组的值 记录此数组内对象的属性 为了懒惰，我使用了数组而不是对象。总是欢迎其他建议。     

解决方法

        您的函数不是真正的可变参数，只需将其签名更改为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;
}

    ,        除非您受到其他一些API的限制，否则我建议的第一件事是：除了要迭代的数据集合外，不要对任何东西使用数组。 这里最好的方法可能是重构函数，使其采用三个参数或某种参数对象。例如：

/**
 * @param {String} searchTerm
 * @param {String} replacementText
 * @param {Object} replacementOpts (optional) An object containing the replacement
 * options; optional values in the object include:<ul>
   <li>catch_errors {Type} description text...</li>
   <li>escape {Type} description text...</li></ul>
 */

我强烈建议您不要使用该数组（再次：“除非您受到控件外部的某些API的约束”），否则它会变得很脆弱，最终会造成一些混乱。