如何在JSDoc中为对象属性添加示例等更复杂的说明信息？

仅使用原生JSDoc完全可以实现需求，有两种常用的兼容方案： #

方案1：为单个属性单独标注JSDoc块 #

直接在对象的每个属性上方添加独立的JSDoc注释，支持任意JSDoc标签（包括@example、@deprecated、@see等），所有主流JSDoc解析工具、IDE都能正常识别：

/**
 * 包含多个简单属性的对象
 * @type {Object}
 */
const myObject = {
  /**
   * 字符串类型的第一个属性
   * @type {String}
   * @example
   * // 读取属性示例
   * const val = myObject.firstProperty
   * console.log(val) // 输出：This is the first property
   */
  firstProperty: 'This is the first property',
  /**
   * 数字类型的第二个属性
   * @type {Number}
   * @example
   * // 属性运算示例
   * const result = myObject.secondProperty * 2
   * console.log(result) // 输出：66
   * @deprecated 该属性将在v2.0版本移除，请使用`newProperty`替代
   */
  secondProperty: 33,
}

方案2：顶部注释块内嵌属性说明 #

如果希望所有注释统一放在对象顶部不拆分，可以在主注释的@description段用Markdown格式编写每个属性的复杂说明，JSDoc原生支持解析描述中的Markdown内容：

/**
 * 包含多个简单属性的对象
 * @type {Object}
 * @property {String} firstProperty 字符串类型的第一个属性
 * @property {Number} secondProperty 数字类型的第二个属性
 * @description 各属性的补充说明与使用示例：
 * ### `firstProperty`
 * 存储基础文本信息，默认值为固定字符串，使用示例：
 * ```js
 * const val = myObject.firstProperty
 * console.log(val) // 输出：This is the first property
 * ```
 * ### `secondProperty`
 * 存储计数数值，取值范围为1-100，使用示例：
 * ```js
 * const result = myObject.secondProperty * 2
 * console.log(result) // 输出：66
 * ```
 */
const myObject = {
  firstProperty: 'This is the first property',
  secondProperty: 33,
}

官方文档中提到@property不支持复杂信息，仅指你无法直接在@property声明行后追加@example等标签，并不代表无法为对象属性添加复杂说明，以上两种均为JSDoc规范内的合法实现。

内容的提问来源于stack exchange，提问作者Gia Phu Tang