Come documentare un tipo di stringa in jsdoc con valori possibili limitati

Sto avendo una funzione che accetta un parametro stringa. Questo parametro può avere solo uno dei pochi valori possibili definiti. Qual è il modo migliore per documentare lo stesso? ShapeType dovrebbe essere definito come enum o TypeDef o qualcos'altro?

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 seconda parte del problema è che i possibili valori di shapeTypenon sono noti nel file che definisce shapeTypecome qualunque cosa tu suggerisca. Ci sono più file forniti da diversi sviluppatori che potrebbero aggiungere ai possibili valori di shapeType.

PS: sto usando jsdoc3

Che ne dici di dichiarare un'enumerazione fittizia:

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

Per questo, però, devi almeno dichiarare l'enumerazione a JSDOC. Ma il codice è pulito e ottieni il completamento automatico in WebStorm.

Tuttavia, il problema dei file multipli non può essere risolto in questo modo.

Alla fine del 2014 in jsdoc3 hai la possibilità di scrivere:

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

Ovviamente questo non sarà riutilizzabile come un'enumerazione dedicata, ma in molti casi un'enumerazione fittizia è eccessiva se viene utilizzata solo da una funzione.

Vedi anche: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808

Che dire:

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

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

Non credo che esista un modo formale di scrivere i valori consentiti in JSDoc .

Puoi certamente scrivere qualcosa @param {String('up'|'down'|'left'|'right')}come l'utente citato b12toaster .

Ma, prendendo riferimento da APIDocjs , ecco cosa uso per scrivere valori vincolati, noti anche come valori consentiti .

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

Oh sì, sto usando ES6.

Questo è il modo in cui il Closure Compiler lo supporta: puoi usare "@enum" per definire un tipo limitato. In realtà non è necessario definire i valori nella definizione di enum. Ad esempio, potrei definire un tipo "intero" come:

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

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

Int è generalmente assegnabile a "numero" (è un numero) ma "numero" non è assegnabile a "Int" senza qualche coercizione (un cast).