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
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.
Oh yeah, I'm using ES6.
What about:
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:
Int is generally assignable to "number" (it is a number) but "number" is not assignable to "Int" without some coercion (a cast).
As of late 2014 in jsdoc3 you have the possibility to write:
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
How about declaring a dummy enum:
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.