JavaScript中，我应该如何注释对象结构？

Question

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

/*
 * @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"
        }
    }
}

我首先通过注释说明资产是一个对象：

@param assets {Object}

但是，我如何进一步评论资产属性本身就是一个值呢？我理解这个问题可能有点偏题，但我只是想确保我的代码注释符合某种语法规则，我无法在这个问题上找到任何信息。

- user2251919

---

我不知道什么是JSDoc，我有点自己编了这个模式。 - user2251919

这个回答解决了你的问题吗？如何在jsdoc中描述“object”参数？ - Simon Zyx

Answer 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?”。详情请见此处和此处。

- calebds

Answer 2

请看JSDoc。我认为这就是你要找的东西。我在我的项目中使用它，它与你使用的模式非常接近。除了它有一个可以为你生成文档的工具。

这里是实际的文档：使用JSDoc

- Sethen

Answer 3

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

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

- Walter Stabosz

---

也许可以更肯定地回答呢？（但是不要加上“编辑：”、“更新：”或类似的内容——回答应该看起来像是今天写的。） - Peter Mortensen