How to document a string type in jsdoc with limited possible values

Question

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? Shoul

Answer 1

What about:

/**
 * @typedef {"keyvalue" | "bar" | "timeseries" | "pie" | "table"} MetricFormat
 */

/**
 * @param format {MetricFormat}
 */
export function fetchMetric(format) {
    return fetch(`/matric}`, format);
}

Answer 2

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.

Answer 3

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

Answer 4

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.

Answer 5

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