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

101

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

Shamasis Bhattacharya
źródło
Problem z wieloma plikami utrudnia to. I zazwyczaj zobaczyć enumw definicji i Unia dla parametru funkcji: ShapeType|string. Jednak wyliczenia nie obsługują dodawania podtypów po deklaracji w kompilatorze Closure.
Chad Killingsworth,
@ChadKillingsworth Rozumiem, co masz na myśli. Utknąłem w punkcie, w którym chcę zdefiniować zestaw właściwości (powiedzmy obiekt, który jest parametrem konstrukcyjnym klasy). Dobrze i dobrze, gdyby wszystkie właściwości konstrukcji zostały określone w jednym miejscu. Niestety, mój kod ma wiele modułów przyczyniających się do tych właściwości konstrukcyjnych. Robienie czegoś w rodzaju mieszania lub podklasowania posiadacza byłoby przesadą! W związku z tym, jeśli mogę po prostu wstrzyknąć definicję listy właściwości, byłoby świetnie.
Shamasis Bhattacharya
Innym podobnym problemem, z którym mam do czynienia, ale z rozproszonymi
listami
Wszystkie poniższe rozwiązania zmuszają nas do stworzenia Enum. W GitHub jest aktywne żądanie funkcji, które znacznie ułatwia ten proces: github.com/jsdoc3/jsdoc/issues/629 . Więc każdy, kto to lubi, prawdopodobnie powinien to uderzyć.
B12Toaster

Odpowiedzi:

27

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.

Sebastian
źródło
Tak. Podejście wyliczeniowe jest jedynym użytecznym sposobem, jaki widzę. W każdym razie przyjmuję to jako jedyną użyteczną odpowiedź - ponieważ problem wielu plików to zupełnie inna historia!
Shamasis Bhattacharya
Problem z tym podejściem polega na tym, że nie pozwala ono na udokumentowanie poszczególnych wartości. Mam problem z JSDoc. github.com/jsdoc3/jsdoc/issues/1065
Gajus
119

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

B12Toaster
źródło
4
Jest to lepsze rozwiązanie, jeśli wiesz, że typ parametru nigdy się nie zmieni.
Luca Steeb
1
Moim zdaniem najlepsze rozwiązanie tego problemu! Dziękuję Ci.
AJC24
29

Co powiesz na:

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

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

wprowadź opis obrazu tutaj

puemos
źródło
9

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 .

wprowadź opis obrazu tutaj

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.

Alan Dong
źródło
0

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).

Jan
źródło
Ale to nie ogranicza możliwych wartości Int. To ta część, której nie jestem pewien, jest możliwa.
Chad Killingsworth
Robi tak samo, jak każda inna adnotacja typu lub wyliczenie w JS. Ograniczenie wynika ze sposobu, w jaki piszesz kod: każde „rzucenie” jest czerwoną flagą. Jeśli ograniczysz odlewy do fabryk wartościowych, otrzymasz to, czego chcesz: nie możesz przypisać „numeru” do „Int” bez ostrzeżenia.
Jan
Nadal nie ogranicza wartości {Int}. :-(
Shamasis Bhattacharya
Jasne, że tak, ograniczasz wartość Int, ograniczając sposób jej tworzenia, a ograniczenie jest wykonywane, gdy wartość jest tworzona. Nie można przypisać surowej liczby, która jest wszystkim, czego potrzebujesz.
John