javascript - 我应该如何在 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"
        }
    }
}

我首先评论 Assets 是一个对象:

@param assets {Object}

但是我该如何继续评论 Assets 的属性本身就是一种值(value)呢？我知道这个问题可能有点跑题，但我只是想确保我的代码注释符合某种语法规则，而且我还没有找到任何关于此事的信息。

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? .