javascript - 如何在 JSDoc 中记录字典？

Question

有下一个例子：

var CONF = {
    locale: {
        "en": {
            name: "English",
            lang: "en-US"
        },
        "es": {
            name: "Spanish",
            lang: "es-ES"
        }
    }
};

并且知道 locale 属性包含的是一个字典对象，它来自数据库，我如何用 JSDoc 记录它的内部属性？

目前我正在考虑typedef 为我的语言环境对象键入，那么我可以将locale属性设置为我定义类型的简单数组吗？这是正确的方法吗？

Answer 1

根据JSDoc 3 文档：

数组和对象（类型应用程序和记录类型）

具有字符串键和数值的对象：

{Object.<string, number>}

所以它会是：

/** @type {{locales: Object.<string, {name: string, lang: string}>}} */
var CONF = {
    locales: {
        en: {
            name: "English",
            lang: "en-US"
        },
        es: {
            name: "Spanish",
            lang: "es-ES"
        }
    }
};

更清洁，使用@typedef

/**
 * @typedef {{name: string, lang: string}} locale
 */
/**
 * @type {{locales: Object.<string, locale>}}
 */
var CONF = {
    locales: {
        en: {
            name: "English",
            lang: "en-US"
        },
        es: {
            name: "Spanish",
            lang: "es-ES"
        }
    }
};

Answer 2

As far as I can tell:

Using @typedef and @property to define a custom type is the "correct" way in JSDoc. But it is cumbersome to write and ugly to read (a cardinal sin in documentation).

The record type is much neater (note the double {{s):

   /** {{
         name:string, 
         lang:string
   }} */