如何描述数据结构？

Question

在编写API文档或代码注释时，我不知道如何描述复杂的数据结构，这个问题困扰了我。

例如，如果我想描述一个包含一些数字的数组，也许我可以将其描述为：Array<Number>。但是，如果我想描述像[{ id: Number, label: String }]这样的对象数组，或者像

那样更加疯狂，该怎么办？

[{ 
    id: Number, 
    label: String, 
    anObj: {
        aDate: Date,
        aRegExp: RegExp
    }
}]

那么有什么流行的规范可以用优雅的方式描述它吗？

Answer 1

我已经使用JSDoc @param来进行这些描述。与@typedef一起使用的相同嵌套规则同样可读。这是一个例子：

    /**
     * ordered list of the most successfull games
     * @typedef {Object} ScoreRecorder~List
     * 
     * @property {Object[]} list - at most {@link options options.list.length} items
     * 
     *   @property {string | Date} list[].timestamp - formatted as LocaleDate or raw
     *   @property {ScoreRecorder~FormatedDuration | number} list[].score - time
     *   elapsed (formatted or number of seconds) or counter result
     *   @property {string} [list[].player=options.list.unknown] - only present if
     *   {@link options options.list.naming} has been set
     * 
     * @property {number} current - 1-based rank of the last successfull
     * game. 0 if not in the highscore list. Raw value conforms to Array.indexOf().
     */

是否可以将它与像jsdoc-to-markdown这样的渲染器一起使用可能会有点昙花一现。上面的例子像这样被转换为markdown（并且需要进行一些调整才能实现）：

ScoreRecorder~List：Object

最成功的游戏的有序列表

善良：ScoreRecorder的内部typedef 的属性

• 列出Array.<Object> - 最多 options.list.length项目
• list [] .timestamp string | Date - 格式化为LocaleDate或raw
• list []。得分FormatedDuration | {{1次 已过去（格式化或秒数）或计数器结果
• list []。player number - 仅出现if options.list.naming已设置
• 当前string - 上一次成功的1级排名 游戏。如果不在高分榜中则为0。原始值符合Array.indexOf（）。