Jak udokumentować typ łańcucha w jsdoc z ograniczonymi możliwymi wartościami

Mam funkcję, która akceptuje jeden parametr ciągu. Ten parametr może mieć tylko jedną z kilku zdefiniowanych możliwych wartości. Jaki jest najlepszy sposób na udokumentowanie tego samego? Czy shapeType należy zdefiniować jako enum, TypeDef czy coś innego?

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

Druga część problemu polega na tym, że możliwe wartości shapeTypenie są znane w pliku, który definiuje shapeTypejako cokolwiek sugerujesz. Istnieje wiele plików przesłanych przez kilku programistów, którzy mogą dodać do możliwych wartości shapeType.

PS: używam jsdoc3

Co powiesz na zadeklarowanie fikcyjnego wyliczenia:

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

W tym celu musisz przynajmniej zadeklarować wyliczenie do JSDOC. Ale kod jest czysty i automatycznie uzupełniasz w WebStorm.

Problemu wielu plików nie można jednak rozwiązać w ten sposób.

Od końca 2014 roku w jsdoc3 masz możliwość pisania:

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

Oczywiście nie będzie to tak samo wielokrotnego użytku jak dedykowane wyliczenie, ale w wielu przypadkach fikcyjne wyliczenie jest przesadą, jeśli jest używane tylko przez jedną funkcję.

Zobacz też: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808

Co powiesz na:

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

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

Nie sądzę, że istnieje formalny sposób zapisywania dozwolonych wartości w JSDoc .

Z pewnością możesz napisać coś takiego, @param {String('up'|'down'|'left'|'right')}jak wspomniany użytkownik b12toaster .

Ale korzystając z referencji z APIDocjsa , oto czego używam do pisania ograniczonych wartości, aka allowedValues .

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

O tak, używam ES6.

W ten sposób obsługuje to Closure Compiler: możesz użyć „@enum”, aby zdefiniować ograniczony typ. W rzeczywistości nie musisz definiować wartości w definicji wyliczenia. Na przykład mogę zdefiniować typ „liczby całkowitej”, taki jak:

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

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

Int jest generalnie przypisywalne do „liczby” (jest to liczba), ale „liczba” nie jest przypisywana do „Int” bez jakiegoś przymusu (rzutowania).