Tengo una función que acepta un parámetro de cadena. Este parámetro solo puede tener uno de los pocos valores posibles definidos. ¿Cuál es la mejor forma de documentar lo mismo? ¿Debe shapeType definirse como enum o TypeDef o algo más?
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;
};
La segunda parte del problema es que los posibles valores de shapeType
no se conocen en el archivo que define shapeType
como lo que sugiera. Hay varios archivos aportados por varios desarrolladores que podrían agregar a los posibles valores de shapeType
.
PD: estoy usando jsdoc3
google-closure-compiler
google-closure
jsdoc
code-documentation
Shamasis Bhattacharya
fuente
fuente
enum
para la definición y una unión para el parámetro de la función:ShapeType|string
. Sin embargo, las enumeraciones no admiten la adición de subtipos después de la declaración en el compilador de cierre.Respuestas:
¿Qué tal declarar una enumeración ficticia?
Sin embargo, debe declarar al menos la enumeración a JSDOC, para esto. Pero el código está limpio y se completa automáticamente en WebStorm.
Sin embargo, el problema de varios archivos no se puede resolver de esta manera.
fuente
A finales de 2014 en jsdoc3 tiene la posibilidad de escribir:
Por supuesto, esto no será tan reutilizable como una enumeración dedicada, pero en muchos casos una enumeración ficticia es una exageración si solo la usa una función.
Véase también: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808
fuente
Qué pasa:
fuente
No creo que haya una forma formal de escribir valores permitidos en JSDoc .
Ciertamente puede escribir algo como el
@param {String('up'|'down'|'left'|'right')}
que mencionó el usuario b12toaster .Pero, tomando como referencia APIDocjs , esto es lo que uso para escribir valores restringidos, también conocidos como allowedValues .
Oh, sí, estoy usando ES6.
fuente
Así es como el compilador de cierre lo admite: puede usar "@enum" para definir un tipo restringido. En realidad, no tiene que definir los valores en la definición de enumeración. Por ejemplo, podría definir un tipo "entero" como:
Int generalmente se puede asignar a "number" (es un número) pero "number" no se puede asignar a "Int" sin alguna coerción (un elenco).
fuente
Int
. Esa es la parte que no estoy seguro de que sea posible.