@chainable

Synopsis:

@chainable

Documents a method as chainable. Such a method must always return this so one can call another method of this same class on the return value. If the method can exit without returning this it shouldn't be marked as chainable.

Example:

/**
 * Shows the component
 * @chainable
 */
show: function() {
    return this.setVisible(true);
},
/**
 * Highlights the component temporarily with yellow color.
 * @chainable
 */
highlight: function() {
    return this.setBackground("yellow").wait(1000).clear();
}

// Then looking at the docs one can safely chain these methods:
myComponent.show().highlight();

Auto-detection

When the code of the method contains return this; JSDuck is often able to auto-detect that the method is chainable. Most importantly the obvious cases like the following will be auto-detected:

/** Some method */
foo: function() {
    this.doSomething();
    return this;
}

While in the following case JSDuck can't tell what the function returns:

/** Some method */
foo: function() {
    return this.doSomething();
}

Generation of @return tags

When using @chainable, or when method is auto-detected as chainable, an appropriate @return tag is automatically generated by JSDuck. For example the following:

/**
 * @chainable
 */
foo: function() {
    ...
}

is equivalent to this:

/**
 * @return {MyClass} this
 * @chainable
 */
foo: function() {
    ...
}