Wie dokumentiere ich ein Wörterbuch in JSDoc?

74

Mit dem nächsten Beispiel:

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

Und wenn ich weiß, dass die Eigenschaft locale ein Wörterbuchobjekt enthält, das aus der Datenbank stammt, wie kann ich seine inneren Eigenschaften mit JSDoc dokumentieren?

Derzeit denke ich daran, typedef für meine Gebietsschemaobjekte zu tippen. Kann ich die localeEigenschaft dann möglicherweise einfach auf ein Array meines definierten Typs festlegen ? Ist das der richtige Weg?

javascript dictionary jsdoc

— Áxel Costas Pena
quelle

123

Laut den JSDoc 3-Dokumenten :

Arrays und Objekte (Typanwendungen und Datensatztypen)

Ein Objekt mit Zeichenfolgenschlüsseln und Zahlenwerten:

{Object.<string, number>}

So wäre es:

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

Reiniger mit @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"
        }
    }
};

— Áxel Costas Pena
quelle

1

Was bedeuten die doppelten geschweiften Klammern?

— Minh Nghĩa

2

@ MinhNghĩa das ist ein Objekt in einer geschweiften Klammer.

— JakeDK

Ja, ich habe das herausgefunden ... VS-Code-Syntax, die FTW

— Minh Nghĩa

2

Soweit ich sagen kann:

Die Verwendung @typedefund @propertyDefinition eines benutzerdefinierten Typs ist in JSDoc die "richtige" Methode. Aber es ist umständlich zu schreiben und hässlich zu lesen (eine Hauptsünde in der Dokumentation).

Der Datensatztyp ist viel übersichtlicher (beachten Sie die doppelten {{s):

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

— Daniel Winterstein
quelle

3

Hmmm ... das dokumentiert einen einzelnen Eintrag im Gebietsschemaobjekt, irre ich mich? Übrigens, dieser Kommentar wird aufgrund der Lang-Beschreibung nicht validiert. Sie sollten ihn entfernen.)

— Áxel Costas Pena

Du liegst nicht falsch! Ich dachte, das wäre das nützlichste Snippet, das Sie erhalten können, da das Gebietsschema var eine Karte von Gebietsschemaobjekten vom benutzerdefinierten Typ ist.

— Daniel Winterstein

Wenn das Wörterbuch auf einem Array basiert, kann es {Array <{Schlüssel: Zeichenfolge, Wert: {Name: Zeichenfolge, Sprache:}}} oder {{Schlüssel: Zeichenfolge, Wert: {Name: Zeichenfolge, Sprache: Zeichenfolge} sein } []} ... noch Objekte sind in der Regel Wörterbuch der Schlüsselwerte in Java-Skript, und in meinem Fall und ÁxelCostasPena-Szenario, ich eher mit ÁxelCostasPena-Lösung gehen.

— DeadManN