google closure compiler - Cómo documentar un tipo de cadena en jsdoc con valores posibles limitados

google-closure-compiler google-closure

Question

Estoy teniendo una función que acepta un parámetro de cadena. Este parámetro puede tener solo uno de los pocos valores posibles definidos. ¿Cuál es la mejor manera de documentar lo mismo? ¿Debería 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 valores posibles 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

Answer 1

¿Qué le parece declarar un enum ficticio?

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

Sin embargo, necesita al menos declarar el enum a JSDOC. Pero el código está limpio y obtiene la finalización automática en WebStorm.

Sin embargo, el problema de los archivos múltiples no se puede resolver de esta manera.

Answer 2

A fines de 2014 en jsdoc3 tienes la posibilidad de escribir:

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

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 es utilizada por una función.

Ver también: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808

Answer 3

Así es como Closure Compiler lo admite: puede usar "@enum" para definir un tipo restringido. En realidad, no tiene que definir los valores en la definición enum. Por ejemplo, podría definir un tipo de "entero" como:

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

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

Int es generalmente asignable a "número" (es un número) pero "número" no se puede asignar a "Int" sin alguna coerción (un molde).

Answer 4

No creo que haya una forma formal de escribir valores permitidos en JSDoc .

Ciertamente puede escribir algo como @param {String(''up''|''down''|''left''|''right'')} como el usuario B12Toaster mencionado.

Pero, tomando referencia de APIDocjs , esto es lo que uso para escribir valores restringidos, también conocidos como valores permitidos .

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

Oh sí, estoy usando ES6.