So dokumentieren Sie einen Zeichenfolgentyp in jsdoc mit begrenzten möglichen Werten

Ich habe eine Funktion, die einen String-Parameter akzeptiert. Dieser Parameter kann nur einen von wenigen definierten möglichen Werten haben. Was ist der beste Weg, um dasselbe zu dokumentieren? Sollte shapeType als enum oder TypeDef oder etwas anderes definiert werden?

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

Der zweite Teil des Problems besteht darin, dass die möglichen Werte von shapeTypein der Datei, die shapeTypeals das definiert ist , was Sie vorschlagen, nicht bekannt sind . Es gibt mehrere Dateien, die von mehreren Entwicklern bereitgestellt wurden und möglicherweise zu den möglichen Werten von beitragen shapeType.

PS: Ich benutze jsdoc3

Wie wäre es mit einer Dummy-Aufzählung:

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

Sie müssen jedoch mindestens die Aufzählung bei JSDOC deklarieren. Der Code ist jedoch sauber und wird in WebStorm automatisch vervollständigt.

Das Problem mit mehreren Dateien kann jedoch nicht auf diese Weise gelöst werden.

Ab Ende 2014 haben Sie in jsdoc3 die Möglichkeit zu schreiben:

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

Natürlich ist dies nicht so wiederverwendbar wie eine dedizierte Aufzählung, aber in vielen Fällen ist eine Dummy-Aufzählung ein Overkill, wenn sie nur von einer Funktion verwendet wird.

Siehe auch: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808

Wie wäre es mit:

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

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

Ich glaube nicht, dass es eine formale Art gibt, zulässige Werte in JSDoc zu schreiben .

Sie können sicherlich so etwas wie den erwähnten @param {String('up'|'down'|'left'|'right')}Benutzer b12toaster schreiben .

Unter Bezugnahme auf APIDocjs verwende ich jedoch Folgendes , um eingeschränkte Werte zu schreiben, auch bekannt als allowValues .

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

Oh ja, ich benutze ES6.

So unterstützt es der Closure Compiler: Mit "@enum" können Sie einen eingeschränkten Typ definieren. Sie müssen die Werte in der Aufzählungsdefinition nicht definieren. Zum Beispiel könnte ich einen "Integer" -Typ definieren wie:

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

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

Int kann im Allgemeinen "Nummer" zugewiesen werden (es ist eine Nummer), aber "Nummer" kann nicht ohne Zwang (Besetzung) "Int" zugewiesen werden.