web-dev-qa-db-ja.com

JSDocで辞書を文書化する方法は？

次の例があります：

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

また、ロケールプロパティに含まれているのはデータベースから取得したディクショナリオブジェクトであることがわかっているので、JSDocを使用してその内部プロパティをドキュメント化するにはどうすればよいですか？

現在、ロケールオブジェクトのtypedef型を考えていますが、localeプロパティを定義済みの型の単純な配列に設定できますか？これは正しい方法ですか？

javascriptdictionaryjsdoc
49
Áxel Costas Pena

JSDoc 3 docs によると：

配列とオブジェクト（型アプリケーションとレコード型）

文字列キーと数値を持つオブジェクト：

{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"
        }
    }
};
77
Áxel Costas Pena

私の知る限り：

@typedefおよび@propertyを使用してカスタムタイプを定義することは、JSDocの「正しい」方法です。しかし、書くのは面倒で、読むのはいです（ドキュメンテーションの重大な罪）。

レコードタイプは非常にきれいです（{{sのダブルに注意してください）：

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