@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);
}

Callback parameters

If parameter is a function, you can document the parameters it gets passed using the same syntax as with object properties (the return property is reserved for documenting the return value):

/**
 * Filters elements in array with given function.
 * @param {Function} fn The callback function.
 * @param {Mixed}    fn.value Value of the element in iteration.
 * @param {Number}   fn.index Index of the element in iteration.
 * @param {Boolean}  fn.return True to keep the element.
 * @param {Object}   scope The scope in which the function is executed.
 */
function filter(fn, scope) {
}

Note: It is important to document callback type as {Function} for JSDuck to recognize it as callback - otherwise it will be treated as a parameter with properties.