How to document more complex informations about a property of an object in JSDoc?

Question

Look at the code down below. So I have an object, and I want to document the properties of it with jsdoc, and so I use the @property tag of jsdoc to document those properties of this myObject object. But, I also want to document more complex informations, like some code examples, not just only simple name, type and descriptions.

But in the documentation of this @property tag, they say we can only add those simple name or descriptions informations, and can not add more complex things (they say: "it does not allow you to provide @examples or similar complex information...").

/**
 * An object with some simple properties
 * @type {Object}
 * @property {String} firstProperty This is the first property with a string value
 * @property {Number} secondProperty This is the second property with a number value
 */
const myObject = {
    firstProperty: 'This is the first property',
    secondProperty: 33,
}

And from there you probably already know what I mean. I want to ask if there is a way to add example codes or more complex information about an object's properties using only JSDoc. Thank you so much!

Answer 1

First, I should note that JsDoc is amazingly flexible and more importantly, will attempt to fill in any details it needs that aren't explicitly tagged (like a description or data types) by parsing your code and extracting what it needs.

But that doesn't mean you only get to document things JsDoc can find in your code.

In fact, you can create documentation for lots of things that do not explicitly exist in your code, if you make sure JsDoc has everything it needs to produce documentation.

At the very least, every "documentable" object must have a name and perhaps a relationship to another object.

Presumably, your object is documented in a module and so you can always add examples to the @module section of your top-level doclet like:

/**
 * Encapsulates the concept of a Widget.
 *
 * @example
 *
 * // assuming we have previously instantiated a disp:Display 
 * 
 * var opts = { ... };
 *
 * var w = new Widget(opts);
 * 
 * w.displayOn(disp);
 *
 * @module
 */

Or, you could add your doc to a named item that does not exist, as in:

/**
 * Example of how to use the Object properties.
 *
 * @name ObjectPropertyExample
 * @memberof MyObject
 *
 * @example
 * ...
 */

In jsdoc, anything you give a @name to will be included in your documentation.

And if you add a @memberof tag, you can assign your new entity to another defined object or even assign it to objects you make up on the fly.

If you don't add a @memberof tag, the item will be associated with the abstract "global" object.

The example above will create a reference to MyObject~ObjectPropertyExample in your docs.

Answer 2

If they say "you can't". You literally can't. 🤷‍♂️