@param

Synopsis:

@param name
Some description...

@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 width
 * @param height
 */

When parameter type is not given (as is the case with auto-detected parameters) it will 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 implode(pieces, glue) {
    glue = glue || ", ";
    return pieces.join(glue);
}

Parameters with properties

If a parameter is expected to have a particular property, you can document that immediately after the @param tag for that parameter, like so:

/**
 * @param user A user record
 * @param user.name The name of the user.
 * @param user.email The email of the user.
 */
function logIn(user) {
    doLogIn(user.name, user.email);
}