Как документировать строковый тип в 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

Ответ 1

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

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

Проблема с несколькими файлами, хотя не может быть решена таким образом.

Ответ 2

Начиная с конец 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

Ответ 3

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

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

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

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

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

Ответ 4

Так компилятор Closure поддерживает его: вы можете использовать "@enum" для определения ограниченного типа. Фактически вам не нужно определять значения в определении перечисления. Например, я могу определить тип "целочисленный", например:

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

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

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