google-closure-compiler - How to document a string type in jsdoc with limited possible values

Question

I am having a function that accepts one string parameter. This parameter can have only one of a few defined possible values. What is the best way to document the same? Should shapeType be defined as enum or TypeDef or something else?

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;
};

The second part of the problem is that the possible values of shapeType is not known in the file that defines shapeType as whatever you suggest. There are multiple files contributed by several developers who might add to the possible values of shapeType.

PS: Am using jsdoc3

Answer 1

截至2014 年底，在 jsdoc3 中，您可以编写：

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

当然，这不会像专用枚举那样可重用，但在许多情况下，如果虚拟枚举仅由一个函数使用，则它是一种过度杀伤力。

另见：https ://github.com/jsdoc3/jsdoc/issues/629#issue-31314808

Answer 2

关于什么：

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

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

Answer 3

如何声明一个虚拟枚举：

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

不过，您至少需要向 JSDOC 声明枚举。但是代码很干净，您可以在 WebStorm 中自动完成。

多文件问题虽然不能以这种方式解决。

Answer 4

我认为在JSDoc中没有正式的编写允许值的方式。

您当然可以编写类似于提到的@param {String('up'|'down'|'left'|'right')}用户b12toaster 之类的内容。

但是，通过参考APIDocjs，这就是我用来编写约束值的方法，也就是allowedValues。

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

哦，是的，我正在使用 ES6。

Answer 5

这就是闭包编译器支持它的方式：您可以使用“@enum”来定义受限类型。您实际上不必在枚举定义中定义值。例如，我可能会定义一个“整数”类型，如：

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

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

Int 通常可以分配给“number”（它是一个数字），但如果没有强制（强制转换），“number”不能分配给“Int”。