如何使用 jsDoc 正确记录类型为“Object”的 vue 属性？答案

【问题标题】：How can I properly document vue properties with type "Object" using jsDoc?如何使用 jsDoc 正确记录类型为“Object”的 vue 属性？
【发布时间】：2021-12-01 16:50:56
【问题描述】：

我想要实现的是记录具有“对象”类型的属性，例如

props: {
    foo: {
        type: Object,
        required: true
    }
}

现在这个对象foo 可以并且将会有多个条目，其中一些是强制性的，而另一些则是可选的。例如

<my-component 
   :foo="{
        mandatoryItem1: 'bar',
        mandatoryItem2: {
            mayBeEvenNested: true
        },
        optionalItem1: 'baz',
        ...
    }"
/>

问题是在使用该属性时，您必须检查组件的源代码才能知道哪些条目必须存在于该属性中。虽然使用 typescript 也可以消除这个问题，但我们现在不能切换到 TS，所以我们必须使用 jsDoc 来代替。我们希望以正确的方式做到这一点。

在记录函数及其参数时，您可以像这样（或类似的）描述嵌套参数对象：

/**
 * @param bar {Object} object containg...
 * @param bar.mandatoryItem1 {String} ...
 * @param bar.mandatoryItem2 {Object} ...
 * @param bar.mandatoryItem2.mayBeEvenNested {Boolean} ...
 */
function foo(bar) {

}

我怎样才能对 vue 属性执行相同或类似的操作？

理想情况下，我们希望将来使用像 vue-styleguidist 这样的东西，以便使用 jsDoc 自动为我们的组件生成文档，因此使用“正确”的语法很重要。

PS：我们希望对“数组”类型的属性也一样，即描述数组中对象的外观。

【问题讨论】：

标签： javascript vue.js jsdoc

【解决方案1】：

你应该有这样的东西：

/**
 * @typedef {Object} Bar
 * @param {String} mandatoryItem1
 * @param {OtherObj} mandatoryItem2
 */

export default {
  name: 'my-component',
  props: {
    /** @type {Bar} */
    foo: { type: Object, required: true }
  }
}

其中OtherObj 是另一种类型定义。

【讨论】：