@override

nene edited this page Dec 6, 2012 · 4 revisions

(Available since JSDuck 4.0)

Synopsis:

@override OverriddenClassName

Documents an Ext JS 4 style override. When used in class doc-comment all the members of the class will be moved over to the class identified by OverriddenClassName as if they were defined inside that class. The class with the @override tag will not show up in documentation.

Auto-detection

One should rarely need to use the @override tag directly as the override: property inside Ext.define() is auto-detected.

/** */
Ext.define("My.Element.Override", {
    override: "Ext.dom.Element",

    /** An additional method for Ext.dom.Element */
    blowUp: function() {
    }
};

The blowUp method will be moved over to Ext.dom.Element and the My.Element.Override class itself will be discarded from documentation. Though the method will get a small note saying that it originates from an override named My.Element.Override. If the Ext.dom.Element already has a blowUp method, then the documentation from the override will be appended to the docs of that method.

Additionally JSDuck detects the Ext.override construct:

/** */
Ext.override(Ext.dom.Element, {
    /**
     * An additional method for Ext.dom.Element
     */
    blowUp: function() {
    }
});

Explicit use of @override tag

However, if you're not using Ext.define to create the override, you need to use the @override tag explicitly. The following code will result in equivalent docs:

/**
 * @class My.Element.Override
 * @override Ext.dom.Element
 */
Ext.apply(Ext.dom.Element.prototype, {
    /**
     * An additional method for Ext.dom.Element
     */
    blowUp: function() {
        // amazing graphics manipulation code here
    }
});

The @class tag is used to give a name for the override. If you don't care about the name, just leave it off and JSDuck will create an anonymous override for you.

Alternative documentation of overrides using @class

Istead of documenting an actual override you could just use an @class tag - all members will then simply be added to that class:

/**
 * @class Ext.dom.Element
 */
Ext.apply(Ext.dom.Element.prototype, {
    /**
     * An additional method for Ext.dom.Element
     */
    blowUp: function() {
        // amazing graphics manipulation code here
    }
});

But the drawback is that this only works for adding new members to a class. If you override an existing method, JSDuck will complain about duplicate members in class - in that case you need to go back and still use the @override tag.