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
*/
...
}
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".)