如何使用JsDoc正确为Vue中Object/Array类型的props编写文档？

以下写法完全符合vue-styleguidist的解析标准，无需TypeScript即可自动生成带完整字段说明的组件文档：

1. Object类型Props注释 #

两种写法都支持，按需选择：

写法1：单独定义类型（推荐，可复用） #

先通过@typedef定义对象的完整结构，再在props注释中引用类型：

/**
 * Foo配置对象结构定义
 * @typedef {Object} FooConfig
 * @property {string} mandatoryItem1 - 必填字符串字段，说明具体用途
 * @property {Object} mandatoryItem2 - 必填嵌套对象
 * @property {boolean} mandatoryItem2.mayBeEvenNested - 嵌套布尔类型必填字段
 * @property {string} [optionalItem1] - 可选字符串字段，非必填项用[]包裹
 * @property {number} [optionalItem2=0] - 有默认值的可选数字字段
 */

export default {
  props: {
    /**
     * 组件核心配置参数
     * @type {FooConfig}
     */
    foo: {
      type: Object,
      required: true
    }
  }
}

写法2：直接嵌套写属性（适合简单一次性结构） #

不需要单独抽类型，直接在props的注释里写字段说明：

export default {
  props: {
    /**
     * 组件核心配置参数
     * @type {Object}
     * @property {string} mandatoryItem1 - 必填字符串字段，说明具体用途
     * @property {Object} mandatoryItem2 - 必填嵌套对象
     * @property {boolean} mandatoryItem2.mayBeEvenNested - 嵌套布尔类型必填字段
     * @property {string} [optionalItem1] - 可选字符串字段
     */
    foo: {
      type: Object,
      required: true
    }
  }
}

2. Array类型Props注释 #

先定义数组元素的结构，再指定props类型为对应类型的数组即可：

/**
 * 数组元素结构定义
 * @typedef {Object} ListItem
 * @property {number} id - 唯一标识，必填
 * @property {string} label - 展示文本，必填
 * @property {boolean} [disabled=false] - 是否禁用，可选，默认false
 */

export default {
  props: {
    /**
     * 渲染用列表数据
     * @type {ListItem[]}
     */
    list: {
      type: Array,
      required: true,
      // 可搭配validator做运行时结构校验
      validator: (val) => val.every(item => item.id && item.label)
    }
  }
}

注意事项 #

• 可选字段统一用方括号包裹属性名，vue-styleguidist会自动标记为非必填
• 字段默认值可在属性名后加=默认值标注
• 以上所有写法都会被vue-styleguidist正确识别，自动生成的文档会完整展示嵌套层级、字段必填状态、类型说明

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