How can I properly document vue properties with type "Object" using jsDoc?

Question

What I am trying to achieve is to document properties that have the type "Object" eg

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

Now this object foo can and will have multiple entries from which some are mandatory while others will be optional. eg

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

Problem is that when using the property you would have to check the source code of the component to know which entries have to be present in the property. While using typescript too eliminate this problem would be great, we can not switch to TS right now, so we have to use jsDoc instead. And we would like to do it the proper way.

When documenting functions and its parameters you can describe a nested parameter object like this (or something like that):

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

}

How can I do the same or anything like this for a vue property?

Ideally we would like to use something like vue-styleguidist in the future so automatically generate the docs for our components using the jsDoc so it is important to use the "right" syntax.

PS: We would like to to the same for properties with type "Array" ie describing how the objects in the array would look like.

Answer 1

You should have something like this:

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

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

where OtherObj is another type definition.