How to document the properties of the object in the JSDoc 3 tag: @this
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';
}
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
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