如何在JSDoc的@typedef定义中将单个属性标记为已废弃？

你之前两种写法不生效的核心原因是JSDoc的标签作用域规则：同一块级注释内，未明确绑定到子标签的顶级@deprecated会默认归属到注释块定义的顶级主体（也就是@typedef声明的类型本身）：

• 把@deprecated写在@property前方时，解析器识别到该标签属于@typedef作用域，但标签后没有对应描述、直接拼接了另一个@property标签，会直接忽略这个无效位置的标签，所以完全不生效。
• 把@deprecated写在@property行尾时，旧版本JSDoc不会把它识别为@property的子属性，仍然会将其归属到@typedef本身，导致整个Foo类型被标记为废弃。

以下是两种纯JSDoc环境下可正常生效的写法，不需要依赖TypeScript：

写法1：同块内联（适用于JSDoc 3.6.0+） #

在@property行内，将@deprecated紧贴属性名书写，后面直接跟废弃说明，不要和属性名断开，高版本JSDoc会自动将该标签绑定到当前属性，不会污染整个类型：

/**
 @typedef {object} Foo
 @property {string} bar - 正常可用属性
 @property {symbol} qux @deprecated - 该属性已废弃，建议替换为bar属性
 */

注意：如果该写法在你的环境中仍然会把整个Foo标记为废弃，说明JSDoc版本过低，请使用下面的兼容写法。

写法2：拆分定义（兼容所有JSDoc版本） #

为需要废弃的属性单独写独立的JSDoc注释块，通过@memberof标签将属性绑定到目标@typedef上，这种写法完全符合JSDoc规范，所有工具和编辑器都能正确识别：

/**
 @typedef {object} Foo
 @property {string} bar - 正常可用属性
 @property {symbol} qux
 */

/**
 * 该属性已废弃，建议替换为bar属性
 * @deprecated
 * @type {symbol}
 * @memberof Foo
 */

使用这种写法时，只有qux属性会被标记为废弃，Foo类型本身和bar等其他属性完全不受影响。

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