我应该如何在 JavaScript 中评论对象结构？答案

【问题标题】：How should I comment object structure in JavaScript?我应该如何在 JavaScript 中评论对象结构？
【发布时间】：2013-05-27 14:51:14
【问题描述】：

我正在使用以下语法来注释我的代码，

/*
 * @param variableName {variableType} Description
 * @return {returnType} Description
 */

但是我现在不知道如何为我的一个对象的构造函数注释我的代码，因为参数是一个对象，并且该对象的字典键本身就是一个参数以及该键的值。

我的参数结构如下；

assets: {

    fruits: {

        rootPath: "files/fruits/",

        images: {

            apple: "apple.png",
            kiwi: "kiwi.png",
            orange: "orange.png",
            peach: "peach.png",
            pear: "pear.png",
            strawberry: "strawberry.png",
            watermelon: "watermelon.png"
        }
    },
    humans: {

        audio: {

            atari: "http://www.universal-soundbank.com/mp3/sounds/18534.mp3"
        }
    }
}

我已经开始评论 assets 是一个对象：

@param assets {Object}

但是我该如何继续评论资产的属性本身就是一个价值呢？我知道这个问题可能有点跑题了，但我只是想确保我的代码 cmet 符合某种语法规则，我还没有找到关于这个问题的任何信息。

【问题讨论】：

我不知道JSDoc是什么，我有点编造了这种模式。

标签： javascript comments

【解决方案1】：

最有用的是将所有对象属性枚举为单独的参数。 [括号] 可选属性，例如：

/**
 *
 * @param {Object} assets Description
 * @param {Object} assets.fruits Description
 * @param {Object} assets.fruits.rootPath Description
 * @param {Object} assets.fruits.images Description
 * @param {Object} [assets.humans] Description
 *
 */

请参阅JSDoc 中的“具有属性的参数”。还有How to describe "object" arguments in jsdoc?。

【讨论】：

【解决方案2】：

看看JSDoc。这就是你要找的，我相信。我在我的项目中使用它，它与您使用的模式非常相似。除了它有一个可以为您生成文档的工具。

这是实际的文档：Use JSDoc

【讨论】：

【解决方案3】：

您使用的注释语法看起来很像JSDoc。

我很确定。 typedef 标签看起来很合适。

【讨论】：

也许让答案更肯定？（但没有“编辑：”、“更新：”或类似的 - 答案应该看起来好像是今天写的。）