@cfg

(Updated for JSDuck 4)

Synopsis:

@cfg
Documentation for the config option.

@cfg name
Documentation for the config option.

@cfg {Type} name
Documentation for the config option.

@cfg {Type} name (required)
Documentation for the config option.

@cfg {Type} [name="default value"]
Documentation for the config option.

@cfg {Type} name.subproperty
Documentation for the config option subproperty.

Documents class configuration option: its name, type and default value. Configs are properties of a configuration object passed to the class constructor (they are common in Ext JS, but might come up in other frameworks too).

Example:

/**
 * @cfg {Boolean} [hidden=false]
 * True to hide panel initially.
 */

Auto-detection

When config options are defined within config: {...} block of Ext.define() JSDuck 4 will auto-detect all those configs:

Ext.define("MyClass", {
    config: {
        /**
         * True to hide panel initially.
         */
        hidden: false,
        // A CSS class for the panel
        cls: "x-my-class",

        maxHeight: 250
    }
});

In the above code the hidden will be detected as public config, cls as a private config with some docs, and maxHeight as a private config without any docs. The same will work with eventedConfig: {...} block. See also @accessor docs for auto-generated getters/setters documentation.

Configs defined outside of config: {...} will work much the same as @property, with the important difference that a @cfg tag needs to be added to distinguish it from a property. Though a @cfg tag can be skipped when documenting a config that's overriding the same config in parent class:

/** Parent class */
Ext.define("Parent", {
    /**
     * @cfg
     * A CSS class name for the component.
     */
    cls: "x-parent"
});

/** Child class */
Ext.define("Child", {
    extend: "Parent",
    cls: "x-child"
});

In the above code the cls in Child class will also be detected as config because the parent has a config with that name. If the parent didn't have cls documented with @cfg, it would be treated there as property and similarly in child.

Objects and functions as config options

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

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

See @param for more details. Configs of Function type are an odd case, but if you really want to, you can have them and even document the parameters.

Required config options

All config options (as the name tells) are optional by default. To document them as required add (required) after the name:

/**
 * @cfg {Ext.data.Store} store (required)
 */

Accessors

Ext4 generates get/set accessor methods for the configs defined inside config: {} block. JSDuck 4 will recognize this automatically, but when it doesn't an @accessor and @evented tags can be used.