How to document the properties of the object in the JSDoc 3 tag: @this

Question

The @param tag allow the documentation of properties, e.g.

 /**
  * @param {Object} userInfo Information about the user.
  * @param {String} userInfo.name The name of the user.
  * @param {String} userInfo.email The email of the user.
  */

How would I document the properties of the @this tag?

 /**
  * @this {Object} 
  * @param {String} this.name The name of the user.
  * @param {String} this.email The email of the user.
  */

I'm wondering if anyone working on the project knows. (The docs are still being created...)

Answer 1

To document instance members, use @name Class#member:

/**
 * Construct a new component
 *
 * @class Component
 * @classdesc A generic component
 *
 * @param {Object} options - Options to initialize the component with
 * @param {String} options.name - This component's name, sets {@link Component#name}
 * @param {Boolean} options.visible - Whether this component is visible, sets {@link Component#visible}
 */
function Component(options) {
   /**
    * Whether this component is visible or not
    *
    * @name Component#visible
    * @type Boolean
    * @default false
    */
    this.visible = options.visible;

   /**
    * This component's name
    *
    * @name Component#name
    * @type String
    * @default "Component"
    * @readonly
    */
    Object.defineProperty(this, 'name', {
        value: options.name || 'Component',
        writable: false
    });
}

This results in a Members section in the documentation that lists each member, its type, default value, and whether it's read only.

The output as generated by [email protected] looks like this:

See also:

• JSDoc namepaths
• @instance tag
• @readonly tag
• @type tag