@param

Synopsis:

@param {Type} name
Some description...

@param {Type} [name]
Some description...

@param {Type} [name="default-value"]
Some description...

@param {Type} name.subproperty
Some description...

Documents parameters for methods and events.

Auto-detection

When no @param tag is used in method documentation and doc-comment is followed by function literal, parameter names are auto-detected from the code:

/**
 * Sets the width and height of the panel.
 */
function setSize(width, height) {
}

The above code is equivalent to this:

/**
 * @method setSize
 * Sets the width and height of the panel.
 * @param {Object} width
 * @param {Object} height
 */

The types of auto-detected parameters will always default to Object. That's why you should not rely much on parameter auto-detection. Though it can be convenient for documenting private methods.

On rare cases you might want to avoid the auto-detection. Like when your method takes a parameter but you want publicly document the method as taking no parameters at all. In such case hide the code behind @ignore and document the method explicitly:

/**
 * @method update
 * Updates content of the container.
 */
/** @ignore */
function update(force) {
}

Optional parameters and default values

All parameters are required by default. To document a parameter as optional, wrap its name in square brackets:

/**
 * Calls function.
 * @param {Function} fn The function to call.
 * @param {Array} [args] Arguments for the function.
 */
function call(fn, args) {
}

You can also follow the parameter name with (optional):

/**
 * @param {Array} args (optional) Arguments for the function.
 */

But this is not as convenient. Plus the square-bracket syntax allows specifying default value for the optional parameter:

/**
 * Joins array of strings into one.
 * @param {String[]} pieces The list of strings to concatenate.
 * @param {Array} [glue=", "] Separator to inject between strings.
 */
function join(pieces, glue) {
}