如何在某些情况下使用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屋!