如何用JSDoc为含短横线字段及不可修改对象添加有效注释？

带短横线的字段（比如"a-b"）因为不符合JavaScript标识符规则，在JSDoc里需要特殊处理，这里分享几种靠谱且易被IDE识别的写法：

1. 用@typedef定义结构化类型（推荐） #

这是可读性和兼容性最好的方式，把带短横线的字段名用引号包裹即可，还能给字段加说明：

/**
 * @typedef {Object} MyCustomObject
 * @property {number} "a-b" - 存储数值的短横线字段
 */

// 直接引用定义好的类型
/** @type {MyCustomObject} */
let a = {"a-b": 5};

2. 直接在@type中使用带引号的字段 #

如果只是临时给单个对象加注释，也可以直接在@type的对象类型里包裹字段名，拆成多行更易被IDE识别：

/**
 * @type {{
 *   "a-b": number
 * }}
 */
let a = {"a-b": 5};

3. 用Record工具类型（适合简单键值对） #

如果你的对象只有这一个带短横线的字段，用Record可以快速定义类型：

/** @type {Record<"a-b", number>} */
let a = {"a-b": 5};

你尝试的/** @type {{"a-b": number}} */写法本身符合JSDoc规范，但旧版本的WebStorm对这种紧凑的带引号对象字面量类型支持不够完善，所以会提示无效。试试下面几种兼容更好的写法：

方案1：@typedef + @property（最稳妥） #

这种写法WebStorm识别度最高，还能保留字段说明：

/**
 * @typedef {Object} NumberObject
 * @property {number} "a-b" - 数值字段
 */

/** @type {NumberObject} */
let a = {"a-b": 5};

方案2：拆分多行的对象类型 #

把@type里的类型拆成多行，WebStorm通常能正确识别：

/**
 * @type {{
 *   "a-b": number
 * }}
 */
let a = {"a-b": 5};

方案3：使用Record类型 #

这种写法简洁，WebStorm对Record的支持很稳定：

/** @type {Record<"a-b", number>} */
let a = {"a-b": 5};

如果你的WebStorm版本偏旧，建议升级到最新版——新版本对带特殊字符的字段JSDoc支持已经改善很多了。

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