@option tag

[gberger]

In JS, the options parameter is a common pattern used to encapsulate many named optional parameters into one object.

It is very important to document what these possible options are, including their name, type, default value and explanation.

Currently, dox has not support for this, apart from using a homebaked list in the method's. An official example shows how this is done:

/**
 * Output the given `str` to _stdout_
 * or the stream specified by `options`.
 * 
 * Options:
 * 
 *   - `stream` defaulting to _stdout_
 * 
 * Examples:
 * 
 *     mymodule.write('foo')
 *     mymodule.write('foo', { stream: process.stderr })
 * 
 */

exports.write = function(str, options) {
  options = options || {};
  (options.stream || process.stdout).write(str);
};

It would be very handy to have an @options tag to document more systematically this important aspect of many functions.

[evindor]

I'm not really sure we should add support for non-standard tags. On the other hand, we already have @api. The problem with @option is that it's not as simple as boolean @api.

I may suggest you to use the following comment style:

/**
 * @param {Object} options
 * @param {string} options.name User's name
 * @param {number} options.age User's age
 */

P.S. Please continue discussion if you feel that we should do it. I see how useful this tag might be. Just want to hear some arguments — it would be great if you could find @option uses in popular projects — i couldn't.