How should I 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.

I don't know what JSDoc is, I have kinda made this pattern up. — user2251919, May 31 '13 at 17:58
Does this answer your question? [How to describe "object" arguments in jsdoc?](https://stackoverflow.com/questions/6460604/how-to-describe-object-arguments-in-jsdoc) — Simon Zyx, May 03 '22 at 07:15

score 21 · Accepted Answer · edited May 23 '17 at 11:46

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

score 1 · Answer 2 · edited Feb 04 '22 at 17:35

1

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

edited Feb 04 '22 at 17:35

Peter Mortensen

30,738
21
105
131

answered May 31 '13 at 17:59

Sethen

11,140
6
34
65

score 0 · Answer 3 · edited Feb 04 '22 at 17:36

0

The comment syntax that you are using looks a lot like JSDoc.

I am pretty sure. The typedef tag looks appropriate.

edited Feb 04 '22 at 17:36

Peter Mortensen

30,738
21
105
131

answered May 31 '13 at 18:01

Walter Stabosz

7,447
5
43
75

Perhaps make the answer more affirmative? (But ***without*** "Edit:", "Update:", or similar - the answer should appear as if it was written today.) – Peter Mortensen Feb 04 '22 at 17:37

How should I comment object structure in JavaScript?

3 Answers3