如何在 JSDoc 中记录字典?

Posted

技术标签:

【中文标题】如何在 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.&lt;string, locale&gt; 中的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 解决方案。跨度>

以上是关于如何在 JSDoc 中记录字典?的主要内容,如果未能解决你的问题,请参考以下文章

dojo js library + jsdoc -> 如何记录代码?

如何使用 jsDoc 在自定义组件中记录此关键字?

在 TypeScript 和/或 JSDoc 中,如何指示记录类型中的某些属性名称是同一类型中兄弟属性的别名?

如何使用 jsdoc-toolkit 记录匿名函数(闭包)

如何使用 JSDoc 记录 CoffeeScript 源代码?

如何使用 JSDoc 记录符号索引签名以符合打字稿?