如何用JSDoc为JS外部类函数属性添加VSCode可识别的带命名参数文档

针对你要为外部类的函数属性生成带命名参数的VSCode提示需求，结合你不能使用TypeScript、只能用@typedef描述类型的限制，正确的JSDoc写法如下：

步骤1：用@callback定义带命名参数的函数类型 #

@callback是JSDoc中专门用于定义函数类型的标签，能让VSCode正确识别参数名、类型和返回值：

/**
 * 获取属性值的函数类型
 * @callback Zzz_GetValueFn
 * @param {string} attributeId - 目标属性的ID
 * @returns {Zzz_Value} 返回对应属性的值
 */

步骤2：在外部类的@typedef中引用该函数类型 #

在描述外部类的@typedef里，直接用定义好的Zzz_GetValueFn作为getValue属性的类型：

/**
 * 外部工具类的类型描述
 * @typedef {Object} Zzz_ExternalClass
 * @property {Zzz_GetValueFn} getValue - 获取指定属性值的方法
 */

为什么之前的方法失效？ #

• 直接在@property里写{function(string):Zzz_Value}属于简写语法，不支持指定参数名，所以VSCode显示arg0；而写function(id:string)不符合JSDoc的类型标注规范，导致完全无法识别。
• 用普通@typedef定义函数类型，VSCode不会自动展开函数的参数和返回值细节，只能识别为通用Function类型。
• 箭头函数形式的@typedef在VSCode的JSDoc类型提示中支持不完善，仅能显示类型名称，无法展开细节。

效果验证 #

完成上述定义后，鼠标悬停在getValue属性上时，VSCode会显示你预期的提示：
(property) getValue: (attributeId: string) => Zzz_Value

关于后续排查 #

如果尝试后仍出现悬停无弹窗、参数无名称的情况，你已经更新VSCode的前提下，可以让同事测试同一代码，排查是否为本地环境（如插件冲突、设置异常）导致的问题。

内容的提问来源于stack exchange，提问作者Reginald Blue