Как документировать переменное число параметров в определенных ситуациях с JSDoc

Question

У меня есть что-то вроде этого, где моя функция принимает только второй и третий параметры, когда первый из них равен != 3. Как я могу документировать это поведение с помощью 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 
*/ 
... 

} 

Answer 1

Насколько я знаю следующее лучшее, что вы можете себе сделать с JSDoc 3. Ключ использовать @also, чтобы указать, что функция имеет более чем одну подпись. Тогда у вас есть заклинание в вашем описании, когда одна подпись относится и когда другой относится и т.д.

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

} 

Это создаст две подписи для функции getTimeframe.

(Примечание: Я предпочитаю использовать number и не Number в случае, как и выше, потому что 1 instanceof Number (например) является false С другой стороны typeof 1 является "number" и typeof Number(1) также "number".).