javascriptcomments

How should I comment object structure in JavaScript?


I am using the following syntax to comment my code,

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

But I now don't know how to comment my code for a constructor of one of my objects as the parameter is an object and that object's dictionary key is a parameter in itself as well as the value of that key.

My structure for the parameter is like below;

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"
        }
    }
}

I have started by commenting that assets is an object:

@param assets {Object}

But how do I then go on to comment that the properties of assets is a value in itself? I understand this question may be a little off-topic, but I just want to make sure that my code comments conform to some kind of syntax rule and I haven't been able to find anything on this matter.


Solution

  • Most informative is to enumerate all object properties as separate parameters. [Bracket] optional properties, e.g:

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

    See "Parameters with Properties" from JSDoc. Also How to describe "object" arguments in jsdoc?.