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

score 69 · Accepted Answer · edited Aug 04 '20 at 09:09

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 jsdoc@3.3.0-alpha3 looks like this:

JSDoc3 output

See also:

how does this work with the ``var Component = function () { } `` paradigm? — Michael Scott Asato Cuthbert, Jun 06 '14 at 21:17
What I was doing wrong was not prefixing the class name with the module name, since I'm using es6 modules — clabe45, Oct 11 '19 at 22:55

Larry Battle · Answer 2 · 2012-05-31T22:25:58.973

6

Use the @property tag to describe the attribute of an object.

@param is used to define the parameters of a method or constructor.

@this is used to define which object this refers to. So here's an example using JSDOC 3.

/**
* @class Person
* @classdesc A person object that only takes in names.
* @property {String} this.name - The name of the Person.
* @param {String} name - The name that will be supplied to this.name.
* @this Person
*/
var Person = function( name ){
    this.name = name;
};

JSDOC 3: https://github.com/jsdoc3/jsdoc

More information: http://usejsdoc.org/index.html

More info: http://code.google.com/p/jsdoc-toolkit/wiki/TagParam

edited May 31 '12 at 22:25

answered May 31 '12 at 22:07

Larry Battle

9,008
4
41
55

5

I believe this actually documents a property of `Person`'s constructor, not of `Person` instances. It also adds an item under in the documentation that says "This • Person", which is not useful. – lazd Jan 23 '14 at 18:51
The ``@this Person`` tag can simply be omitted. It's redundant within the ``@class`` block. – Ignitor Jul 15 '16 at 13:09
1

The JSDoc docs states "The @property tag is a way to easily document a list of static properties of a class, namespace or other object." - so its not for non-static properties – Dakusan Sep 18 '18 at 07:45

score 2 · Answer 3 · answered Jul 15 '16 at 13:31

Within the constructor of a class, jsdoc will realize by itself that the documented properties belong to class intances. So this should be enough:

/**
 * @classdesc My little class.
 *
 * @class
 * @memberof module:MyModule
 * @param {*} myParam Constructor parameter.
 */
function MyLittleClass(myParam) {
    /**
     * Instance property.
     * @type {string}
     */
    this.myProp = 'foo';
}

If it is not clear for jsdoc that the function is the class constructor, you can use @this to define what this refers to:

/**
 * @classdesc My little class.
 *
 * @class
 * @memberof module:MyModule
 * @name MyLittleClass
 * @param {*} myParam Constructor parameter.
 */

// Somewhere else, the constructor is defined:
/**
 * @this module:MyModule.MyLittleClass
 */
function(myParam) {
    /**
     * Instance property.
     * @type {string}
     */
    this.myProp = 'foo';
}

Does only work on the first level but not for nested objects — Ini, Mar 09 '20 at 10:41

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

3 Answers3