VS的Add jsdoc comments插件生成默认参数JSDoc语法是否合规？

结论 #

你使用「Add jsdoc comments」插件生成的注释不符合JSDoc规范，属于插件生成逻辑的缺陷。

存在的问题 #

你示例中@param {} invoiceUpdate=false写法有两处错误：

• 类型标注位为空：JSDoc要求@param后的大括号内必须填写对应参数的类型，该参数默认值为布尔值false，类型为boolean，空括号属于无效标注
• 默认值标注格式错误：JSDoc规定带默认值的可选参数，需要将参数名和默认值一同包裹在方括号内，而非直接写在参数名后方

正确的标注方式 #

标准JSDoc规范写法

/**
 * @param  {string[]} invoiceIds
 * @param  {string} token
 * @param  {boolean} [invoiceUpdate=false]
 * @returns {Promise<string>}
 */
public async calculateInvoices(
  invoiceIds: string[],
  token: string,
  invoiceUpdate = false,
): Promise<string> {
  /* 函数逻辑 */
}

TypeScript环境简化写法

因为你已经在TS代码中声明了所有参数和返回值的类型，JSDoc可以只保留描述信息，无需重复标注类型：

/**
 * 计算发票金额
 * @param invoiceIds 要计算的发票ID列表
 * @param token 接口鉴权令牌
 * @param invoiceUpdate 是否更新发票数据，默认为false
 * @returns 处理结果字符串
 */
public async calculateInvoices(
  invoiceIds: string[],
  token: string,
  invoiceUpdate = false,
): Promise<string> {
  /* 函数逻辑 */
}

内容的提问来源于stack exchange，提问作者Kavindu Vindika