Как задокументировать строковый тип в jsdoc с ограниченными возможными значениями

У меня есть функция, которая принимает один строковый параметр. Этот параметр может иметь только одно из нескольких определенных возможных значений. Как лучше всего задокументировать то же самое? Следует ли определять shapeType как enum, TypeDef или что-то еще?

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

Вторая часть проблемы заключается в том, что возможные значения shapeTypeнеизвестны в файле, который определяет shapeTypeвсе, что вы предлагаете. Есть несколько файлов, добавленных несколькими разработчиками, которые могут добавить к возможным значениям shapeType.

PS: Я использую jsdoc3

Как насчет объявления фиктивного перечисления:

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

Однако для этого вам нужно хотя бы объявить перечисление в JSDOC. Но код чистый, и вы получаете автозаполнение в WebStorm.

Однако проблема с несколькими файлами не может быть решена таким образом.

По состоянию на конец 2014 года в jsdoc3 у вас есть возможность написать:

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

Конечно, это будет не так многоразово, как выделенное перечисление, но во многих случаях фиктивное перечисление является излишним, если оно используется только одной функцией.

См. Также: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808

Что о:

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

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

Я не думаю, что существует формальный способ записи разрешенных значений в JSDoc .

Вы, конечно, можете написать что-то @param {String('up'|'down'|'left'|'right')}вроде упомянутого пользователя b12toaster .

Но, взяв ссылку из APIDocjs , вот что я использую для записи ограниченных значений, также известных как allowedValues .

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

Ах да, я использую ES6.

Это то, как компилятор Closure поддерживает это: вы можете использовать «@enum» для определения ограниченного типа. На самом деле вам не нужно определять значения в определении перечисления. Например, я мог бы определить «целочисленный» тип, например:

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

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

Int обычно присваивается «number» (это число), но «number» не может быть присвоено «Int» без некоторого принуждения (приведения).