@method

nene edited this page Aug 9, 2012 · 6 revisions

(Updated for JSDuck 4)

Synopsis:

@method
Documentation for the method.

@method name
Documentation for the method.

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

Example:

/**
 * @method area
 * Returns area of a circle
 * @param {Number} r Radius of the circle.
 * @return {Number} The area
 */

See @param and @return for further details on these most commonly used tags inside method documentation.

Auto-detection

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

/**
 * Returns area of a circle
 * @param {Number} r Radius of the circle.
 * @return {Number} The area
 */
function area(r) {
}

Assignment of function literal works as well:

/**
 * Returns area of a circle
 */
var area = function(r) {
}

As does the use inside object literal:

{
    /**
     * Returns area of a circle
     */
    area: function(r) {
    }
}

JSDuck also understands Ext.emptyFn and treats the following as a method documentation:

/**
 * Returns area of a circle
 */
MyClass.prototype.area = Ext.emptyFn;

JSDuck 4 will also pick up all the doc-comment-less methods defined inside Ext.define(), Ext.extend() orobject literal`:

Ext.define("MyClass", {
    someMethod: function() {
    }
});

See @class docs for more details on this.

The following code would not be detected as a method if we weren't using the @method tag. JSDuck does however detect the name:

/**
 * @method
 * Iterates over items in array.
 */
Array.forEach = (function() {
    if (Array.prototype.forEach) {
        return Array.prototype.forEach;
    }
    else {
        return function() { ... };
    }
})();

Template methods

Sometimes a method is provided as a hook for extending the functionality of the class. Such methods should be marked with @template (this tag usually goes along with @protected):

/**
 * called when this Component's DOM structure is created.
 * @template
 * @protected
 */
onRender: function() {
}