如何在某些情况下使用JSDoc记录可变数量的参数 [英] How to document variable number of parameters in certain situations with JSDoc

问题描述

我有类似的东西，当第一个是!= 3时，我的函数只接受第二个和第三个参数.如何使用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
 */
...

}

推荐答案

据我所知，目前使用jsdoc 3可以做到最好.关键是使用@also表示该函数具有更多功能.不止一个签名.然后，当一个签名适用时和另一个签名适用时，您便在说明中清楚说明了.

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

}

这将为getTimeframe函数创建两个签名.

This will create two signatures for the getTimeframe function.

(注意:在上述情况下，我更喜欢使用number而不是Number，因为1 instanceof Number(例如)是false.另一方面，typeof 1是"number"和typeof Number(1)也是"number".)

(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".)

这篇关于如何在某些情况下使用JSDoc记录可变数量的参数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！