如何使用jsDoc正确地记录具有"Object“类型的vue属性？

Question

我试图实现的是记录具有"Object“类型的属性。

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

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

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

问题是，在使用该属性时，您必须检查组件的源代码，才能知道属性中必须有哪些条目。虽然使用打字本也可以消除这个问题，但是我们现在不能切换到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:对于具有" array“类型的属性，我们希望使用相同的方法，即描述数组中的对象的样子。

Answer 1

你应该有这样的东西：

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

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

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