CODEWITHSUNDEEP
javascriptjsdoc
Valentin
Valentin

Reputation: 2858

How to document variable number of parameters in certain situations with JSDoc

I have something like this where my function only takes in the second and third parameters when the first one is != 3. How can I document this behaviour with JSDoc?

getTimeframe: function(timeframe, since, until) {
/*
 * @param {Number} timeframe Can be 0, 1, 2 or 3
 * @param {Number} since Optional when timeframe !== 3
 * @param {Number} until Optional when timeframe !== 3
 */
...

}

Upvotes: 2

Views: 490

Answers (1)

Louis
Louis

Reputation: 151511

As far as I know the following is the best you can currently do with jsdoc 3. The key is to use @also to indicate that the function has more than one signature. Then you have spell out in your description when one signature applies and when the other applies, etc.

/**
 * When the <code>timeframe</code> parameter is not 3...
 *
 * @param {number} timeframe Can be 0, 1, 2.
 * @param {number} [since] blah.
 * @param {number} [until] blah.
 *
 * @also
 *
 * When the <code>timeframe</code> is 3, then...
 *
 * @param {number} timeframe Set to 3.
 */
function getTimeframe(timeframe, since, until) {

}

This will create two signatures for the getTimeframe function.

(Note: I prefer using number and not Number in a case like above because 1 instanceof Number (for instance) is false. On the other hand typeof 1 is "number" and typeof Number(1) is also "number".)

Upvotes: 5

Related Questions