javascript 在JSDoc中记录开放参数函数的正确方法

zphenhs4  于 2023-01-01  发布在  Java
关注(0)|答案(4)|浏览(125)

假设您有以下内容:

var someFunc = function() {
    // do something here with arguments
}

如何正确地证明这个函数可以在JSDoc中接受任意数量的参数?这是我最好的猜测,但我不确定它是否正确。

/**
 * @param {Mixed} [...] Unlimited amount of optional parameters
 */
var someFunc = function() {
    // do something here with arguments
}

相关项目:php - How to doc a variable number of parameters

nx7onnlm

nx7onnlm1#

JSDoc规范和Google的闭包编译器是这样做的:

@param {...number} var_args

其中“number”是所需参数的类型。
那么,它的完整用法如下所示:

/**
* @param {...*} var_args
*/
function lookMaImVariadic(var_args) {
    // Utilize the `arguments` object here, not `var_args`.
}

请注意有关使用arguments(或arguments的某个偏移量)访问其他参数的注解。var_args只是用来向IDE发出该参数确实存在的信号。
Rest parameters in ES6可以使真实的参数更进一步以包含所提供的值(因此不再需要使用arguments):

/**
* @param {...*} var_args
*/
function lookMaImES6Variadic(...var_args) {
    // Utilize the `var_args` array here, not `arguments`.
}
p1iqtdky

p1iqtdky2#

JSDoc文档中描述了如何执行此操作,它使用了与Closure文档类似的省略号。

@param {...<type>} <argName> <Argument description>

省略号后面需要提供一个类型,但是可以使用*来描述接受任何内容,或者使用|来分隔多个可接受的类型。在生成的文档中,JSDoc将此参数描述为 repeatable,就像它将可选参数描述为 optional 一样。
在我的测试中,实际的javascript函数定义中不需要参数,所以实际的代码可以只包含空括号,即function whatever() { ... }
单一类型:

@param {...number} terms Terms to multiply together

任何类型(在下面的示例中,方括号表示items将被标记为可选和可重复):

@param {...*} [items] - zero or more items to log.

多个类型需要在类型列表两边加上括号,在左括号前加上省略号:

@param {...(Person|string)} attendees - Meeting attendees, listed as either 
                                        String names or {@link Person} objects
zf9nrax1

zf9nrax13#

JSDoc users group
没有任何官方的方法,但一个可能的解决方案是这样的:

/**
 * @param [...] Zero or more child nodes. If zero then ... otherwise ....
 */

方括号表示可选参数,...(对我来说)表示"某个任意数字"。
另一种可能是...

/**
 * @param [arguments] The child nodes.
 */

无论哪种方式都应该传达你的意思。
这是一个有点过时,虽然(2007年),但我不知道有什么更当前。
如果需要将参数类型记录为"mixed",请使用{*},如@param {*} [arguments]中所示。

cunj1qz1

cunj1qz14#

我已经为此烦恼了一段时间。下面是如何使用Google闭包编译器:

/**
* @param {...*} var_args
*/
function my_function(var_args) {
    // code that accesses the magic 'arguments' variable...
}

关键是给予你的函数一个var_args参数(或者你在@param语句中调用它的任何东西),即使这个函数实际上并没有使用这个参数。

相关问题