How to document a string type in jsdoc with limited possible values
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
What about:
/**
* @typedef {"keyvalue" | "bar" | "timeseries" | "pie" | "table"} MetricFormat
*/
/**
* @param format {MetricFormat}
*/
export function fetchMetric(format) {
return fetch(`/matric}`, format);
}
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.
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.