如何使用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。另一方面{{1 } {是typeof 1而"number"也是typeof Number(1)。）