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

90

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

— Shamasis Bhattacharya
quelle

Das Problem mit mehreren Dateien macht dies schwierig. Normalerweise sehe ich eine enumfür die Definition und eine Vereinigung für den Funktionsparameter : ShapeType|string. Aufzählungen unterstützen jedoch nicht das Hinzufügen von Untertypen nach der Deklaration im Closure-Compiler.

— Chad Killingsworth

@ChadKillingsworth Ich verstehe, was du meinst. Ich stecke an einem Punkt fest, an dem ich eine Reihe von Eigenschaften definieren möchte (sagen wir ein Objekt, das als Konstruktionsparameter einer Klasse dient). Es ist gut und schön, wenn alle Eigenschaften der Konstruktion an einem Ort definiert wurden. Leider enthält mein Code eine Reihe von Modulen, die zu diesen Konstruktionseigenschaften beitragen. Etwas wie ein Mixin zu machen oder das Eigentum zu unterordnen, würde über Bord gehen! Wenn ich einfach in eine Eigenschaftslistendefinition einfügen kann, wäre das großartig.

— Shamasis Bhattacharya

Ein weiteres ähnliches Problem, mit dem ich konfrontiert bin, aber mit einer verteilten Immobilienliste, ist stackoverflow.com/questions/19113571/…

— Shamasis Bhattacharya

Alle unten aufgeführten Lösungen zwingen uns, eine Aufzählung zu erstellen. Bei GitHub gibt es eine aktive Funktionsanforderung, um diesen Vorgang erheblich zu vereinfachen: github.com/jsdoc3/jsdoc/issues/629 . Jeder, der es mag, sollte es wahrscheinlich stoßen.

— B12Toaster

24

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.

— Sebastian
quelle

Ja. Der Aufzählungsansatz ist der einzige brauchbare Weg, den ich sehe. Wie auch immer, ich akzeptiere dies als die einzig brauchbare Antwort - da das Problem mit mehreren Dateien eine ganz andere Geschichte ist!

— Shamasis Bhattacharya

Das Problem bei diesem Ansatz ist, dass die einzelnen Werte nicht dokumentiert werden können. Ich habe ein Problem mit JSDoc. github.com/jsdoc3/jsdoc/issues/1065

— Gajus

106

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

— B12Toaster
quelle

4

Dies ist eine bessere Lösung, wenn Sie wissen, dass sich der Parametertyp niemals ändern wird.

— Luca Steeb

1

Aus meiner Sicht die beste Lösung dafür! Danke dir.

— AJC24

24

Wie wäre es mit:

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

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

— Puemos
quelle

8

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.

— Alan Dong
quelle

0

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.

— John
quelle

Dies schränkt jedoch die möglichen Werte von nicht ein Int. Das ist der Teil, von dem ich nicht sicher bin, ob er möglich ist.

— Chad Killingsworth

Es macht so viel wie jede andere Typanmerkung oder Aufzählung in JS. Die Einschränkung ergibt sich aus der Art und Weise, wie Sie den Code schreiben: Jede "Besetzung" ist eine rote Fahne. Wenn Sie die Besetzungen auf Wertfabriken beschränken, erhalten Sie, was Sie wollen: Sie können 'Int' nicht ohne Warnung 'Nummer' zuweisen.

— John

Die Werte von {Int} werden immer noch nicht eingeschränkt. :-(

— Shamasis Bhattacharya

Sicher, Sie beschränken den Wert von Int, indem Sie einschränken, wie er erstellt wird, und die Einschränkung erfolgt, wenn der Wert erstellt wird. Es kann keine Rohnummer vergeben werden, was alles ist, was Sie brauchen.

— John