How to document a string type in jsdoc with limited possible values
Solution 1
How about declaring a dummy enum:
/**
* Enum string values.
* @enum {string}
*/
Enumeration = {
ONE: "The number one",
TWO: "A second number"
};
/**
* Sample.
* @param {Enumeration} a one of the enumeration values.
*/
Bar.prototype.sample = function(a) {};
b = new Bar();
bar.sample(Enumeration.ONE)
You need to at least declare the enum to JSDOC, for this, though. But the code is clean and you get auto-completion in WebStorm.
The multiple files problem though cannot be solved this way.
Solution 2
As of late 2014 in jsdoc3 you have the possibility to write:
/**
* @param {('rect'|'circle'|'ellipse')} shapeType - The allowed type of the shape
*/
Shape.prototype.getType = function (shapeType) {
return this.type;
};
Of course this will not be as reusable as a dedicated enum but in many cases a dummy enum is an overkill if it is only used by one function.
See also: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808
Solution 3
What about:
/**
* @typedef {"keyvalue" | "bar" | "timeseries" | "pie" | "table"} MetricFormat
*/
/**
* @param format {MetricFormat}
*/
export function fetchMetric(format) {
return fetch(`/matric}`, format);
}
Solution 4
I don't think there's a formal way of writing allowed values in JSDoc.
You certainly can write something like @param {String('up'|'down'|'left'|'right')}
like user b12toaster mentioned.
But, by taking reference from APIDocjs, here's what I use for writing constrained values, aka allowedValues.
/**
* Set the arrow position of the tooltip
* @param {String='up','down','left','right'} position pointer position
*/
setPosition(position='left'){
// YOUR OWN CODE
}
Oh yeah, I'm using ES6.
Solution 5
This is how the Closure Compiler supports it: you can use "@enum" to define a restricted type. You don't actually have to define the values in enum definition. For instance, I might define an "integer" type like:
/** @enum {number} */
var Int = {};
/** @return {Int} */
function toInt(val) {
return /** @type {Int} */ (val|0);
}
Int is generally assignable to "number" (it is a number) but "number" is not assignable to "Int" without some coercion (a cast).
Shamasis Bhattacharya
Technical architect, strategist and a developer specialising in JavaScript framework development. Architected and developed FusionCharts data visualisation library.
Updated on September 19, 2020Comments
-
Shamasis Bhattacharya almost 4 years
I am having a function that accepts one string parameter. This parameter can have only one of a few defined possible values. What is the best way to document the same? Should shapeType be defined as enum or TypeDef or something else?
Shape.prototype.create = function (shapeType) { // shapeType can be "rect", "circle" or "ellipse"... this.type = shapeType; }; Shape.prototype.getType = function (shapeType) { // shapeType can be "rect", "circle" or "ellipse"... return this.type; };
The second part of the problem is that the possible values of
shapeType
is not known in the file that definesshapeType
as whatever you suggest. There are multiple files contributed by several developers who might add to the possible values ofshapeType
.PS: Am using
jsdoc3
-
Chad Killingsworth over 10 yearsBut that doesn't restrict the possible values of
Int
. That's the part I'm not sure is possible. -
John over 10 yearsIt does as much as any other type annotation or enum in JS. The restriction comes from how you write the code: every "cast" is a red flag. If you limit the casts to value factories then you get what you want: you can't assign 'number' to 'Int' without a warning.
-
Shamasis Bhattacharya over 10 yearsIt still doesn't restrict the values of {Int}. :-(
-
Shamasis Bhattacharya over 10 yearsYes. The enumeration approach is the only usable way I see. Anyways, I accept this as the only usable answer - since the multi-file problem is another story altogether!
-
John over 10 yearsSure it does, you restrict the value of Int by limiting how it is created and the restriction is done when the value is created. A raw number can not be assigned which is all you need.
-
Gajus almost 9 yearsThe problem with this approach is that it does not allow to document the individual values. I have an issue with JSDoc. github.com/jsdoc3/jsdoc/issues/1065
-
Luca Steeb about 8 yearsThis is a better solution if you know that the param type will never change.
-
AJC24 about 4 yearsBest solution to this in my view! Thank you.
-
RiZKiT over 2 years
@param
does not allow this type of syntax. The most standard way would be@param {"up"|"down"|"left"|"right"} [position=left] - pointer position
.