How to comment object structure in javascript?

Question

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.

Answer 1

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

Answer 2

Take a look at JSDoc. This is what you're looking for, I believe. I use this in my projects and it follows closely to the same pattern as what you're using. Except it has a tool that will generate documentation for you.

Here's the actual documentation: Use JSDoc