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

Shamasis Bhattacharya picture Shamasis Bhattacharya · Sep 30, 2013 · Viewed 27.3k times · Source

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 defines shapeType as whatever you suggest. There are multiple files contributed by several developers who might add to the possible values of shapeType.

PS: Am using jsdoc3

Answer

B12Toaster picture B12Toaster · Jan 12, 2016

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