@property

(Updated for JSDuck 4)

Synopsis:

@property
Documentation for the property.

@property name
Documentation for the property.

@property {Type} name
Documentation for the property.

@property {Type} [name="default value"]
Documentation for the property.

@property {Type} name.subproperty
Documentation for the subproperty.

Documents the property: its name, type and default value.

Example:

/**
 * @property {Boolean} [hidden=false]
 * True when panel is hidden.
 */

Auto-detection

Anything that isn't found to be a class, method, event or config, is treated as property. So often the @property tag is not even needed as it's the default. The following is equivalent of the above:

/**
 * True when panel is hidden.
 */
Ext.Panel.prototype.hidden = false;

Here the name (hidden), type (Boolean) and default value (false) of the property are all auto-detected.

Within classes defined with Ext.define(), Ext.extend() and object literal, auto-detection is even more extensive. In the following code JSDuck 4 will pick up both baseName and maxHeight properties, they will get documented as private as they have no doc-comment:

Ext.define("MyClass", {
    // A private property with some documentation
    baseName: "foo",

    maxHeight: 7
});

In next example the @property tag is used to force JSDuck to treat BASE_URL as a property (otherwise it will think it is a class name becase it begins with an uppercase letter):

/**
 * @property
 * Base URL to use for Ajax requests.
 */
Ext.Ajax.BASE_URL = "/";

JsDuck will auto-detect Number, String, Boolean, RegExp and Function types when it sees the corresponding literal assigned to the property. For properties of Function type you need to use the @property tag again, as otherwise JSDuck will see a function and think it's a method documentation.

Additionally arrays of these literals will be detected:

/**
 * CSS class names to apply for root element.
 */
cls: ["x-component", "x-item"],

Here the cls property will be detected with type String[] and default value ["x-component", "x-item"].

With anything else the type will default to Object and default value to undefined (which will not be shown in the documentation). That's why if you want to completely avoid auto-detection of default value, specify it explicitly as undefined:

/**
 * @property {String} [baseName=undefined]
 */
baseName: "foo",

Object properties and function properties

The syntax is the same as used for @param tag:

/**
 * @property user A user record
 * @property user.name The name of the user.
 * @property user.email The email of the user.
 */
user: {},

Properties of Function type are an odd case, but if you really want to, you can have them and even document the parameters.

Read-only properties

To mark that property should not be modified, use the @readonly tag.

Using @type

For backwards compatibility the @type tag can also be used to denote a property and document its type. For new code always use the @property tag instead.