Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to document an "object" parameter of a method

I'm trying to write some documentation for a JavaScript method using YUIDoc. It looks like:

/** 
    Returns an instance of className

    @method getInstance
    @param {string} className the of the class used to create the instance
    @param {Object} options these are options used to create the instance
**/
function getInstance(className, options) { ..... }

Now, the options object can have several parameters, like options.id, options.single, etc.

How do I add this information to the documentation of this @param?

like image 598
Jeanluca Scaljeri Avatar asked Mar 13 '13 21:03

Jeanluca Scaljeri


2 Answers

From reference: http://yui.github.com/yuidoc/syntax/index.html

"As shown in the example, you can also nest @param tags. This enables you to document object parameters that have their own particular nested structure."

@param {Object} [options] Data 
  to be mixed into the event 
  facade of the `change` 
  event(s) for these attributes.
  @param {Boolean} [options.silent]
    If `true`, no `change` event 
    will be fired.
like image 96
apelsinapa Avatar answered Sep 28 '22 00:09

apelsinapa


In YUIDOC 0.3.45, which is the current version at the time of writing, in order to describe objects received by methods you should first declare the object (options, in the example below) and then it's properties with a dot notation (for example, options.url).

/**
 * Describe your method
 *
 * @method yourMethodName
 * @param {object} options - These are the options you may pass
 * @param {string} options.url - the url
 * @param {string} options.otherOption - description of other option
 */
like image 35
Yair Tavor Avatar answered Sep 28 '22 02:09

Yair Tavor