How to document a dictionary in JSDoc?

Solution 1:

According to the JSDoc 3 docs:

Arrays and objects (type applications and record types)

An object with string keys and number values:

{Object.<string, number>}

So it would be:

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

Cleaner, using @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"
        }
    }
};

Solution 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
   }} */