nene edited this page Mar 20, 2012 · 6 revisions

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.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.