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
– user2251919, Commented May 31, 2013 at 17:58
Does this answer your question? How to describe "object" arguments in jsdoc? — Simon Zyx
– Simon Zyx, Commented May 3, 2022 at 7:15

Community · Accepted Answer · 2017-05-23 11:46:54Z

22

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

edited May 23, 2017 at 11:46

CommunityBot

11 silver badge

answered May 31, 2013 at 18:05

calebds

26.3k9 gold badges51 silver badges75 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

Cody Gray · Accepted Answer · 2025-01-18 11:29:16Z

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.

edited Jan 18 at 11:29

Cody Gray♦

246k53 gold badges512 silver badges591 bronze badges

answered May 31, 2013 at 17:59

Sethen

11.4k6 gold badges38 silver badges67 bronze badges

Comments

Walter Stabosz · Accepted Answer · 2025-01-21 14:59:40Z

0

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

The typedef tag looks appropriate.

edited Jan 21 at 14:59

answered May 31, 2013 at 18:01

Walter Stabosz

7,7955 gold badges48 silver badges79 bronze badges

Collectives™ on Stack Overflow

How should I comment object structure in JavaScript?

3 Answers 3

Comments

Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

Comments

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related