web-dev-qa-db-fra.com

Comment documenter un dictionnaire dans JSDoc?

Avoir l'exemple suivant:

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

Et sachant que ce que contient la propriété locale est un objet dictionnaire, qui provient de la base de données, comment puis-je documenter ses propriétés internes avec JSDoc?

Actuellement, je pense à typedef taper pour mes objets régionaux, puis-je être en mesure de définir la propriété locale à simplement un tableau de mon type défini? Est-ce que c'est la bonne façon de le faire?

javascriptdictionaryjsdoc
49
Áxel Costas Pena

Selon les documents JSDoc :

Tableaux et objets (types d'application et types d'enregistrement)

Un objet avec des clés de chaîne et des valeurs numériques:

{Object.<string, number>}

Ce serait donc:

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

Plus propre, en utilisant @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"
        }
    }
};
77
Áxel Costas Pena

Autant que je sache:

En utilisant @typedef et @property pour définir un type personnalisé est la manière "correcte" dans JSDoc. Mais il est lourd à écrire et laid à lire (un péché cardinal dans la documentation).

Le type d'enregistrement est beaucoup plus net (notez le double {{s):

   /** {{
         name:string, 
         lang:string
   }} */
2
Daniel Winterstein