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 shapeType
nie są znane w pliku, który definiuje shapeType
jako 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
google-closure-compiler
google-closure
jsdoc
code-documentation
Shamasis Bhattacharya
źródło
źródło
enum
w definicji i Unia dla parametru funkcji:ShapeType|string
. Jednak wyliczenia nie obsługują dodawania podtypów po deklaracji w kompilatorze Closure.Odpowiedzi:
Co powiesz na zadeklarowanie fikcyjnego wyliczenia:
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.
źródło
Od końca 2014 roku w jsdoc3 masz możliwość pisania:
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
źródło
Co powiesz na:
źródło
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 .
O tak, używam ES6.
źródło
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:
Int jest generalnie przypisywalne do „liczby” (jest to liczba), ale „liczba” nie jest przypisywana do „Int” bez jakiegoś przymusu (rzutowania).
źródło
Int
. To ta część, której nie jestem pewien, jest możliwa.