Cómo documentar un tipo de cadena en jsdoc con valores posibles limitados

Tengo una función que acepta un parámetro de cadena. Este parámetro solo puede tener uno de los pocos valores posibles definidos. ¿Cuál es la mejor forma de documentar lo mismo? ¿Debe shapeType definirse como enum o TypeDef o algo más?

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;
};

La segunda parte del problema es que los posibles valores de shapeTypeno se conocen en el archivo que define shapeTypecomo lo que sugiera. Hay varios archivos aportados por varios desarrolladores que podrían agregar a los posibles valores de shapeType.

PD: estoy usando jsdoc3

¿Qué tal declarar una enumeración ficticia?

/**
 * 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)

Sin embargo, debe declarar al menos la enumeración a JSDOC, para esto. Pero el código está limpio y se completa automáticamente en WebStorm.

Sin embargo, el problema de varios archivos no se puede resolver de esta manera.

A finales de 2014 en jsdoc3 tiene la posibilidad de escribir:

/**
 * @param {('rect'|'circle'|'ellipse')} shapeType - The allowed type of the shape
 */
Shape.prototype.getType = function (shapeType) {
  return this.type;
};

Por supuesto, esto no será tan reutilizable como una enumeración dedicada, pero en muchos casos una enumeración ficticia es una exageración si solo la usa una función.

Véase también: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808

Qué pasa:

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

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

No creo que haya una forma formal de escribir valores permitidos en JSDoc .

Ciertamente puede escribir algo como el @param {String('up'|'down'|'left'|'right')}que mencionó el usuario b12toaster .

Pero, tomando como referencia APIDocjs , esto es lo que uso para escribir valores restringidos, también conocidos como allowedValues .

/**
 * Set the arrow position of the tooltip
 * @param {String='up','down','left','right'} position pointer position
 */
setPosition(position='left'){
  // YOUR OWN CODE
}

Oh, sí, estoy usando ES6.

Así es como el compilador de cierre lo admite: puede usar "@enum" para definir un tipo restringido. En realidad, no tiene que definir los valores en la definición de enumeración. Por ejemplo, podría definir un tipo "entero" como:

/** @enum {number} */
var Int = {};

/** @return {Int} */
function toInt(val) {
  return /** @type {Int} */ (val|0);
}

Int generalmente se puede asignar a "number" (es un número) pero "number" no se puede asignar a "Int" sin alguna coerción (un elenco).