如何用有限的可能值记录 jsdoc 中的字符串类型

我有一个接受一个字符串参数的函数。此参数只能具有少数已定义的可能值之一。记录相同内容的最佳方法是什么？ShapeType 是否应该定义为枚举或 TypeDef 或其他形式？

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

问题的第二部分是，无论您建议什么，在定义 shapeType的文件中，shapeType的可能值是未知的。有多个开发人员提供的多个文件可能会添加到 shapeType的可能值中。

PS: 正在使用 jsdoc3

44886 次浏览
小开

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

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


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

Int 通常可以赋值给“ number”(它是一个数字) ，但是如果没有强制(强制转换) ，“ number”不能赋值给“ Int”。

小开
最佳答案

如何声明一个虚拟枚举:

/**
* 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 申报 enum。但是代码是干净的，你可以在 WebStorm 中自动完成。

但是多文件问题不能用这种方法解决。

小开

从 jsdoc3中的 2014年底开始，你可以写:

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

小开

我不认为在 JSDoc中有一种正式的写允许值的方法。

您当然可以像用户 B12烤面包机提到的那样编写类似于 @param {String('up'|'down'|'left'|'right')}的代码。

enter image description here

但是，通过引用 APIDocjs，下面是我用来编写约束值的方法，也就是 允许值。

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

是的，我用的是 ES6。

小开

那么:

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


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

enter image description here


提交答案