Як задокументувати тип рядка в 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 , ось що я використовую для написання обмежених значень, інакше дозволених значень .

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

О так, я використовую ES6.

Ось як підтримує компілятор закриття: ви можете використовувати "@enum", щоб визначити обмежений тип. Насправді вам не потрібно визначати значення у визначенні переліку. Наприклад, я можу визначити тип "цілого числа", наприклад:

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

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

Int, як правило, можна присвоїти "номеру" (це число), але "число" не можна призначити "Int" без певного примусу (приведення).