Como documentar um tipo de string em jsdoc com valores possíveis limitados

Estou tendo uma função que aceita um parâmetro de string. Este parâmetro pode ter apenas um dos poucos valores possíveis definidos. Qual é a melhor maneira de documentar o mesmo? O shapeType deve ser definido como enum ou TypeDef ou algo mais?

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

A segunda parte do problema é que os valores possíveis de shapeTypenão são conhecidos no arquivo que define shapeTypeo que você sugere. Existem vários arquivos contribuídos por vários desenvolvedores que podem adicionar aos valores possíveis de shapeType.

PS: Estou usando jsdoc3

Que tal declarar um enum fictício:

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

Você precisa pelo menos declarar o enum para JSDOC, para isso, no entanto. Mas o código está limpo e você obtém o preenchimento automático no WebStorm.

O problema de vários arquivos, porém, não pode ser resolvido desta forma.

No final de 2014 em jsdoc3, você tem a possibilidade de escrever:

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

É claro que isso não será tão reutilizável quanto um enum dedicado, mas em muitos casos um enum fictício é um exagero se for usado apenas por uma função.

Veja também: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808

A respeito:

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

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

Não acho que haja uma maneira formal de escrever valores permitidos no JSDoc .

Você certamente pode escrever algo @param {String('up'|'down'|'left'|'right')}como o usuário b12toaster mencionado.

Mas, tomando a referência de APIDocjs , aqui está o que uso para escrever valores restritos, também conhecidos como valores permitidos .

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

Sim, estou usando o ES6.

É assim que o Closure Compiler o suporta: você pode usar "@enum" para definir um tipo restrito. Na verdade, você não precisa definir os valores na definição de enum. Por exemplo, posso definir um tipo "inteiro" como:

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

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

Int é geralmente atribuível a "número" (é um número), mas "número" não pode ser atribuído a "Int" sem alguma coerção (um elenco).