Daniel Baird Daniel Baird -4 years ago 59
Javascript Question

The right way to use JSDoc to document a data object's members, when I add them one by one?

I have a JS data object that just holds some static items. I'm not declaring it all in one go inside { }; I start with an empty object, and add items in one at a time. E.g:

var ScapeStuff = {};

// some generic stuff
ScapeStuff.generic = new SomeClass(...);

// water
ScapeStuff.water = new SomeClass(...);

// dirt of various moisture levels
var dry = someValue
var wet = anotherValue
// interpolate moisture...
ScapeStuff.dirt0 = new SomeClass(dry);
ScapeStuff.dirt1 = new SomeClass((dry + dry + wet) / 3);
ScapeStuff.dirt2 = new SomeClass((dry + wet + wet) / 3);
ScapeStuff.dirt3 = new SomeClass(wet);

// some other types of stuff..

// finally, export this data object
module.exports = ScapeStuff;

I'd like to doc my ScapeStuff data object with JSDoc, and replace the comment lines like
// water
with JSDoc comments that describe that thing.

I could just add a giant JSDoc comment above the
ScapeStuff = {}
, and use
to write a description for each property item, but the file could be quite long, so what I really want is to have the JSDoc comments for each property in the source right before that property.

What's the right way to have inline JSDoc comments in this situation?

Answer Source

Found the answer myself.

First, I document the ScapeStuff container as a @namespace like this:

 * Stuff (that is, THREE.Material) that things in scapes can be made out of.
 * @namespace
var ScapeStuff = {};

Now I can use @memberof to tell JSDoc that each new thing I add to the initially empty object, is a member of the ScapeStuff namespace.

/** some generic stuff
  * @memberof ScapeStuff */
ScapeStuff.generic = new SomeClass(...);

/** water
  * @memberof ScapeStuff */
ScapeStuff.water = new SomeClass(...);

So, I get my wish -- I can document the members where they occur in the source, and still have JSDoc show them as being inside the parent object. Yay me!

Recommended from our users: Dynamic Network Monitoring from WhatsUp Gold from IPSwitch. Free Download