Как документировать словарь в JSDoc?

Следующий пример:

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

И зная, что свойство locale содержит объект словаря, который поступает из базы данных, как я могу документировать его внутренние свойства с помощью JSDoc?

В настоящее время я думаю о типе typedef для моих локальных объектов, тогда могу ли я установить свойство locale как просто массив моего определенного типа? Правильно ли это сделать?

Ответ 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"
        }
    }
};

Ответ 2

Насколько я могу сказать:

Использование @typedef и @property для определения пользовательского типа является "правильным" способом в JSDoc. Но писать громоздко и читать некрасиво (основной грех в документации).

Тип записи гораздо аккуратнее (обратите внимание на двойные {{ s):

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