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 {...}包含搜索词，替换词及其选项的数组; 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...

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

记录变量参数的类型（在本例中为数组）
记录此数组的值
记录此数组中对象的属性

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

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标准，它是谷歌使用他们的文档

/**
 * 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;
}

Answer 2

除非你受到其他API的限制，否则我建议的第一件事就是：除了你打算迭代的数据集之外，不要使用数组。

这里最好的方法可能是对函数进行重新分解，使得它需要三个参数或者某种param对象。例如：

/**
 * @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的限制），因为它会变得脆弱，最终会有点混乱。

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

2 个答案: