如何正确使用JSDoc为数组展开参数编写文档？

刚好碰到过这个问题！你用{Array<String>}注释...args的时候，WebStorm会误以为你需要传入一个数组参数，但你的函数实际是接收多个独立的字符串参数，所以才会弹出类型错误提示。

解决方法很简单，用JSDoc的「可变参数」语法就行，直接在类型前面加三个点...，告诉IDE这个参数是用来收集任意数量的同类型值的：

/**
 * 测试函数，接收任意数量的字符串参数
 * @param {...string} args - 任意数量的字符串参数，函数内部会将它们收集为一个数组
 */
function test(...args) {
  // 这里args会被WebStorm识别为string[]类型，数组方法（如map、forEach）都会有正常提示
}

test('a', 'b', 'c'); // 现在IDE不会再报类型错误了

为什么这个写法管用？因为...string明确告诉JSDoc：这个参数是「零个或多个字符串」，最终会被打包成数组。这样一来，你调用函数时传多个字符串，IDE会检查每个参数的类型是否符合；在函数内部，args也会被正确识别为string[]类型，完全不影响后续的代码提示。

如果你更习惯用Array<String>或者string[]的写法，也可以配合@rest标签来标注这是一个rest参数：

/**
 * 测试函数，接收任意数量的字符串参数
 * @param {string[]} args - 由多个字符串参数收集而成的数组
 * @rest
 */
function test(...args) {
  // ...
}

不过第一种...string的写法更简洁，也是目前主流IDE（包括WebStorm）支持最好的方式，推荐优先使用。

内容的提问来源于stack exchange，提问作者Maksim Nesterenko