How to document an "object" parameter of a method

Question

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?

Google Closure Compiler would mark that up as {{id:string,single:whatever}} or {Object.} if it's a general dictionary, but I don't know if this is common syntax or an extension to it. See the bottom of this page: https://developers.google.com/closure/compiler/docs/js-for-compiler — Dave, Mar 13 '13 at 21:30

score 6 · Answer 1 · answered Jul 17 '14 at 05:37

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
 */

Is there a way to denote required attributes like this? Adding `@required` below the param doesnt work. — JDillon522, Jan 12 '16 at 19:11

score 5 · Accepted Answer · answered Mar 13 '13 at 21:33

5

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.

answered Mar 13 '13 at 21:33

apelsinapa

575
3
9

Hi @apelsinapa, the link is not found. – Sam Apr 29 '22 at 10:26

How to document an "object" parameter of a method

2 Answers2