如何在 JSDoc 中记录字典？

Posted 2023-02-23

【中文标题】如何在 JSDoc 中记录字典？

【英文标题】：How to document a dictionary in JSDoc?

【发布时间】：2013-10-31 02:12:58

【问题描述】：

有下一个例子：

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

知道 locale 属性包含的是一个字典对象，它来自数据库，我如何用 JSDoc 记录它的内部属性？

目前我正在考虑为我的语言环境对象设置typedef 类型，那么我可以将locale 属性设置为我定义类型的简单数组吗？这是正确的做法吗？

【参考方案1】：

根据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"
        
    
;

【讨论】：

双花括号是什么意思？

@MinhNghĩa 这是一个大括号内的对象。

是的，我发现了... VS Code 语法高亮 FTW

知道如何将Object.<string, locale> 中的string 的名称从x 更改为其他名称吗？

【参考方案2】：

据我所知：

使用@typedef 和@property 定义自定义类型是JSDoc 中“正确”的方式。但是写起来很麻烦，读起来很难看（文档中的一个大罪）。

记录类型更简洁（注意双s）：

   /** 
         name:string, 
         lang:string
    */

【讨论】：

嗯...这记录了语言环境对象中的单个条目，我错了吗？顺便说一句，由于语言描述，该评论 doesn't validate，您应该将其删除；）

你没有看错！我认为这是提供给您的最有用的 sn-p，因为 locale var 是自定义类型的 locale 对象的映射。

如果字典是基于数组的，它可以是 Array 或 key:string, value: name:string, lang:string[]... 仍然对象往往是 java-script 中键值的字典，在我的情况下，以及 ÁxelCostasPena 场景，我更喜欢使用 ÁxelCostasPena 解决方案。跨度>