@class

(Updated for JSDuck 4)

Synopsis:

@class
Documentation for the class.

@class ClassName
Documentation for the class.

Documents the name of the class; or leaves the name for auto-detection and forces the documented entity to be treated as class.

Example:

/**
 * @class Ext.Component
 * @extends Ext.AbstractComponent
 * Base class for all Ext components.
 */

Auto-detection

This tag is auto-detected when doc-comment is right above Ext.define. The following code is equivalent of the above one:

/**
 * Provides searching of Components.
 */
Ext.define("Ext.Component", {
    extend: "Ext.AbstractComponent",
    ...
});

Note: When no extend: or @extends used with Ext.define, the parent class will default to Ext.Base. When not using Ext.define the parent class will default to Object.

Auto-detection of Ext3 style class definition with Ext.extend is also supported:

/**
 * Provides searching of Components.
 */
Ext.Component = Ext.extend(Ext.AbstractComponent, {
    ...
});

Finally a class will be detected when doc-comment is before a variable looking like a class name. This code is again equivalent to the above ones:

/**
 * A simple class.
 * @extends Ext.AbstractComponent
 */
Ext.Component = function() {
};

Function declaration works too. Here a Component class extending Object will be detected:

/**
 * A simple class.
 */
function Component() {
}

But when the last part of the name begins with a lowercase letter, class auto-detection fails:

/**
 * I meant this to be a class, but JSDuck thinks it's not.
 */
Ext.supports = {};

In such case use the @class tags to force JSDuck treat it as class:

/**
 * @class
 * I'm a class now.
 */
Ext.supports = {};

@constructor tag inside class

This use is deprecated. See @constructor for details.

@cfg tags inside class

For backwards compatibility with old ext-doc the class documentation may contain @cfg tags:

/**
 * @class Ext.Panel
 * The one-and-only panel class.
 *
 * @cfg {Boolean} hidden
 * True if panel should be hidden at first.
 * @cfg {String} title
 * Text to use as the title of the panel.
 */

Instead of doing this, JSDuck recommends you document each configuration option separately:

/**
 * @class Ext.Panel
 * The one-and-only panel class.
 */

    /**
     * @cfg {Boolean} hidden
     * True if panel should be hidden at first.
     */
    /**
     * @cfg {String} title
     * Text to use as the title of the panel.
     */

The code is a bit longer, but it's now consistent with how other members are documented, plus it allows using additional tags like @private on each config option separately.

Other tags inside class

The following tags are specifically meant to be used inside class documentation:

• @alternateClassName
• @mixins
• @requires
• @uses
• @singleton
• @aside
• @alias
• @ftype
• @ptype
• @xtype
• @override

Also the following tags work in class context:

• @private
• @ignore
• @deprecated
• @removed
• @author
• @docauthor
• @inheritdoc
• @abstract

Class members

Class members (configs, properties, methods, events) are automatically assigned to the class after which they appear in the source code. It's best to explain with an example:

/**
 * @property
 * Current height of the Panel.
 */
Ext.Panel.prototype.height = 0;

/**
 * The one-and-only panel class.
 */
Ext.define("Ext.Panel", {
    /**
     * @cfg {String}
     * Text to use as the title of the panel.
     */
    title: false
});
/**
 * Hides the panel.
 */
Ext.Panel.prototype.hide = function() {};

/**
 * The core element class.
 */
Ext.define("Ext.Element", {
    /**
     * @event click
     * Fired when element is clicked on.
     */
});

Here the title config and hide method will be assigned to Ext.Panel class while the click event will go to Ext.Element. The height property however does not follow any class, so JSDuck assumes it's global and places it into special global class. Normally you don't want to have global properties, so JSDuck prints a warning when such a thing happens.

As can be seen from the code, this property should belong to Ext.Panel class. To correct this mistake you can use @member to explicitly document where the member belongs:

/**
 * @property
 * Current height of the Panel.
 * @member Ext.Panel
 */
Ext.Panel.prototype.height = 0;

JSDuck 4 additionally detects all the members within Ext.define(), Ext.extend() and object literal that don't have a doc-comment as private members:

Ext.define("MyClass", {
    title: "Hello",
    // True to show the component
    hidden: false,
    show: function() {
    }
});

Here the private title and hidden properties are auto-detected and the private show method. The comment of hidden property is also detected. Similarly this will work:

var MyClass = Ext.extend(Object, {
    title: "Hello",
    // True to show the component
    hidden: false,
    show: function() {
    }
});

And this:

var MyClass = {
    title: "Hello",
    // True to show the component
    hidden: false,
    show: function() {
    }
};

Or in case you're using some kind of other construct for creating your class, which JSDuck doesn't natively understand, you can place a @class tag right in front of the object literal containing class members:

makeClass("MyClass", /** @class MyClass */ {
    title: "Hello",
    show: function() {
    }
};

Static members

All class members are by default documented as instance members, but methods and properties can also be static. JSDuck 4 auto-detects members as static when they are defined inside statics: {...} or inheritableStatics: {...} blocks. See @static tag for details.

Member visibility and other common tags

There are three main visibility levels: public, protected and private. Additionally members can be abstract, deprecated, removed, hidden and ignored. By default every documented member is public.

The following tags can be used in all members:

• @private - member which may only be accessed from the the class itself.

• @protected - member which may only be accessed from the class itself and its subclasses.

• @abstract - an implementation for the member must be provided in subclasses.

• @deprecated - member is supported for backwards compatibility and may be removed in future versions.

• @removed - member existed in earlier version but has been removed since. Useful for giving directions to users upgrading from older version.

• @hide - hides a member of a parent class. Useful if child class doesn't support everything parent supports. (One should generally keep the Liskov substitution principle in mind though.)

• @ignore - removes the member completely from documentation. As if the doc-comment never was there.