Support different sets of parameters for a function

[GoogleCodeExporter]

There are cases where a the parameters to a function may have dramatically
different meaning, depending on what parameters are passed in.  It would be
nice to have a way to document this.  For example, jGDoc supports a
@paramset property that allows this sort of documentation:

/**
 * @paramset just the max
 * @param {Number} max max value to return
 *
 * @paramset min and max
 * @param {Number} min min value to return
 * @param {Number} max max value to return
 */
function rnd(minOrMax, max) {
  var min = arguments.length == 1 ? 0 : minOrMax;
  var min = arguments.length == 2 ? max : minOrMax;
  return Math.floor(min + (max-min)*Math.random);
}

A more complex example is a function that takes a "cmd" argument that
specifies a command, with any following parameters being dependent on what
the command is. E.g.:

/**
 * @paramSet Get a list of whatever
 * @param cmd "list"
 *
 * @paramSet Remove the specified item
 * @param cmd "remove"
 * @param {Number} id Item to remove
 *
 * @paramSet Copy the specified item
 * @param cmd "create"
 * @param {Object} options Creation options
 * @param {Number} options.id id of item to create
 * @param {Number} options.name Name of item to copy
 */
function doAction(cmd) {
}

Original issue reported on code.google.com by broofa on 12 Feb 2009 at 5:16

[GoogleCodeExporter]

Please note that this is different from the issue of how to document an 
arbitrary
number of parameters (via @param [...])

See also http://code.google.com/p/jgrousedoc/wiki/TagParamset

Original comment by broofa on 12 Feb 2009 at 5:18

[GoogleCodeExporter]

Original comment by micmath on 15 Feb 2009 at 12:14

• Changed state: Accepted
• Added labels: Milestone-Release3.0, Priority-Low, Type-Enhancement