javascript - comment - ¿Cómo documentar un diccionario en JSDoc?

jsdoc return

Question

Tener el siguiente ejemplo:

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

Y sabiendo que lo que contiene la propiedad locale es un objeto de diccionario, que proviene de la base de datos, ¿cómo puedo documentar sus propiedades internas con JSDoc?

Actualmente estoy pensando en typedef type para mis objetos locale, ¿entonces puedo ser capaz de establecer la propiedad locale simplemente como una matriz de mi tipo definido? ¿Esta es la manera correcta de hacerlo?

Answer 1

De acuerdo con los documentos JSDoc 3 :

Arrays y objetos (tipo de aplicaciones y tipos de registro)

Un objeto con claves de cadena y valores numéricos:

{Object.<string, number>}

Entonces sería:

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

Cleaner, usando @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

Por lo que yo puedo decir:

Usar @typedef y @property para definir un tipo personalizado es la forma "correcta" en JSDoc. Pero es engorroso escribir y feo leer (un pecado capital en la documentación).

El tipo de registro es mucho más ordenado (observe el doble {{s):

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