web-dev-qa-db-fra.com

Comment documenter un type de chaîne dans jsdoc avec des valeurs possibles limitées

J'ai une fonction qui accepte un paramètre de chaîne. Ce paramètre ne peut avoir qu'une seule des quelques valeurs possibles définies. Quelle est la meilleure façon de documenter la même chose? Faut-il définir shapeType comme enum ou TypeDef ou autre chose?

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 deuxième partie du problème est que les valeurs possibles de shapeType ne sont pas connues dans le fichier qui définit shapeType comme ce que vous proposez. Il existe plusieurs fichiers fournis par plusieurs développeurs qui pourraient ajouter aux valeurs possibles de shapeType.

PS: j'utilise jsdoc3

google-closure-compilergoogle-closurejsdoccode-documentation
64
Shamasis Bhattacharya

Que diriez-vous de déclarer une énumération fictive:

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

Pour cela, vous devez au moins déclarer l'énumération à JSDOC. Mais le code est propre et vous obtenez l'auto-complétion dans WebStorm.

Le problème de plusieurs fichiers ne peut cependant pas être résolu de cette façon.

14
Sebastian

Depuis fin 2014 en jsdoc3 vous avez la possibilité d'écrire:

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

Bien sûr, cela ne sera pas aussi réutilisable qu'une énumération dédiée, mais dans de nombreux cas, une énumération fictive est une exagération si elle n'est utilisée que par une seule fonction.

Voir aussi: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808

66
B12Toaster

Qu'en est-il de:

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

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

enter image description here

7
puemos

Je ne pense pas qu'il existe un moyen formel d'écrire les valeurs autorisées dans JSDoc .

Vous pouvez certainement écrire quelque chose comme @param {String('up'|'down'|'left'|'right')} comme user b12toaster mentionné.

enter image description here

Mais, en prenant référence à APIDocjs , voici ce que j'utilise pour écrire des valeurs contraintes, aka allowedValues ​​.

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

Oh ouais, j'utilise ES6.

3
Alan Dong

Voici comment le compilateur de fermeture le prend en charge: vous pouvez utiliser "@enum" pour définir un type restreint. Vous n'avez en fait pas besoin de définir les valeurs dans la définition d'énumération. Par exemple, je pourrais définir un type "entier" comme:

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

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

Int est généralement attribuable à "nombre" (c'est un nombre) mais "numéro" n'est pas attribuable à "Int" sans une certaine contrainte (un cast).

0
John