Documenting the same jsduck config type across multiple methods

Question

Two questions:

First, does anyone know how to inherit part of some documentation? Specifically for an "options" object:

 * @param {Object}          opts
 * @param {String}          opts.effect    Transition effect.  fade|slide
 * @param {String}          opts.direction Direction to do the transition, when applicable.  up|down|left|right
 * @param {String|Number}   opts.duration  Transition duration in ms, or one of short|long
 * @param {String|Function} opts.timing    Transition timing function, or one of

Basically, I want that documentation in multiple methods, but I don't want to copy it to each method, and I want a common place to change it.

Second, If I can inherit the documentation some how, can I extend it? e.g. I want:

method foo:
    opts.opt-a // inherited
    opts.opt-b // inherited
    opts.opt-c // inherited
    opts.opt-d // local to this method

Answer 1

This kind of inheriting is not supported.

What you could do instead, is to document this options object as a documentation-only-class instead:

/**
 * @class FooOpts
 * A configuration object for Foo, instantiated with object literal.
 */
/** @cfg {String} effect */
/** @cfg {String} direction */
/** @cfg {String|Number} duration */
/** @cfg {String|Function} timing */

And then use this documentation-only-class as your parameter type:

* @param {FooOpts} opts Config object for the FooOpts class.

To override the options, you could define a subclass.

Depending on the number of options that you have, the overhead of this approach might not be justified. But maybe the fact that you're specifying the same options in several places, is a sign that you would indeed be better off creating an actual concrete class for them.