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

【问题标题】：How to document a string type in jsdoc with limited possible values如何用有限的可能值在 jsdoc 中记录字符串类型
【发布时间】：2013-10-06 07:11:16
【问题描述】：

我有一个接受一个字符串参数的函数。此参数只能具有几个已定义的可能值之一。记录相同内容的最佳方法是什么？ shapeType 是否应该定义为 enum 或 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

【问题讨论】：

多文件问题使这变得困难。我通常会看到 enum 的定义和函数参数的联合：ShapeType|string。但是枚举不支持在 Closure-compiler 中声明后添加子类型。
@ChadKillingsworth 我明白你的意思。我被困在我想定义一组属性的地方（比如说一个作为类的构造参数的对象）。如果建筑的所有属性都在一个位置定义，那就太好了。不幸的是，我的代码有许多模块有助于构建属性。做一些像 mixin 或子类化属性的事情会过火！因此，如果我可以简单地注入到属性列表定义中，那就太好了。
我面临的另一个类似问题，但分布式属性列表是stackoverflow.com/questions/19113571/…
以下所有解决方案都强制我们创建一个枚举。 GitHub 上有一个活跃的功能请求，可以让这个过程变得更容易：github.com/jsdoc3/jsdoc/issues/629。所以任何喜欢它的人都应该碰它。

标签： google-closure-compiler google-closure jsdoc code-documentation

【解决方案1】：

从 jsdoc3 中的late 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

【讨论】：

如果您知道参数类型永远不会改变，这是一个更好的解决方案。
我认为最好的解决方案！谢谢。

【解决方案2】：

怎么样：

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

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

【讨论】：

【解决方案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 中自动完成。

虽然不能这样解决多文件问题。

【讨论】：

是的。枚举方法是我看到的唯一可用的方法。无论如何，我接受这是唯一可用的答案 - 因为多文件问题完全是另一回事！
这种方法的问题是它不允许记录单个值。我对 JSDoc 有疑问。 github.com/jsdoc3/jsdoc/issues/1065

【解决方案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。

【讨论】：

@param 不允许这种类型的语法。最标准的方式是@param {"up"|"down"|"left"|"right"} [position=left] - pointer position。

【解决方案5】：

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

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

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

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

【讨论】：

但这并不限制Int 的可能值。那是我不确定是否可行的部分。
它与 JS 中的任何其他类型注释或枚举一样多。限制来自您编写代码的方式：每个“演员”都是危险信号。如果您将强制转换限制为值工厂，那么您将得到您想要的：您不能在没有警告的情况下将 'number' 分配给 'Int'。
它仍然不限制 {Int} 的值。 :-(
确实如此，您通过限制 Int 的创建方式来限制 Int 的值，并且在创建值时完成限制。无法分配原始数字，这就是您所需要的。