如何使用 jsDoc 正確記錄類型為“Object”的 vue 屬性？

Question

我想要實現的是記錄具有“對象”類型的屬性，例如

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：我們希望對類型為“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是另一種類型定義。