Enum 作为 JSDoc 中的 @param 类型

Question

是否可以对 JSDoc

@param

类型声明使用枚举，如下例所示？

/**
 * @enum { Number }
 */
const TYPES = {
    TYPE_A: 1,
    TYPE_B: 2
}

/**
 * @param { TYPES } type
 */
function useTypesEnum( type ) {
    
}

如果我使用 Eclipse 等 IDE 来处理 JavaScript，应该不会出现警告？

Answer 1

您可以通过这样做来实现这一目标：

/**
* @param {(1|2)} type
*/
function useTypesEnum(type) {

}

Answer 2

所以这似乎是在没有任何警告的情况下记录所有内容的正确方法

/**
 * @typedef {number} MyType
 **/


/**
 * @enum {MyType}
 */
var TYPES = {
    TYPE_A: 1,
    TYPE_B: 2
}

/**
 * @param {MyType} type
 */
function useTypesEnum( type ) {

}

这意味着：

• MyType 是一个数字
• TYPES 是一个保存 MyType 值的枚举
• 此函数接受输出 MyType 值的枚举

在 intellij 2017.1 上为我工作

但是 - 这仍然允许将每个字符串传递给函数而不发出警告。

如果您也想指定枚举值 - 因此如果使用另一个字符串，它应该会引发错误，请使用以下描述的方法：https://stackoverflow.com/a/36501659/1068746

 /**
    * @typedef FieldType
    * @property {string} Text "text"
    * @property {string} Date "date"
    * @property {string} DateTime "datetime"
    * @property {string} Number "number"
    * @property {string} Currency "currency"
    * @property {string} CheckBox "checkbox"
    * @property {string} ComboBox "combobox"
    * @property {string} Dropdownlist "dropdownlist"
    * @property {string} Label "label"
    * @property {string} TextArea "textarea"
    * @property {string} JsonEditor "jsoneditor"
    * @property {string} NoteEditor "noteeditor"
    * @property {string} ScriptEditor "scripteditor"
    * @property {string} SqlEditor "sqleditor"
    */

Answer 3

我使用以下内容：

const TYPES = {
    0: "TYPE_A",
    1: "TYPE_B"
}

/**
 * @param {keyof TYPES} type
 */
function useTypesEnum(type) {
    // ...
}

这显示了 VSCode 中建议的正确值。它具有良好的可读性，为开发人员提供了关于哪个值代表什么以及可以在运行时使用枚举值的线索。

---

如果我在运行时不需要

TYPES

的值，我什至更喜欢使用

TYPES

作为

@typedef

:

/**
 * @typedef {{ 
 *     0: "TYPE_A",
 *     1: "TYPE_B"
 * }} TYPES
 */

/**
 * @param {keyof TYPES} type
 */
function useTypesEnum(type) {
    // ...
}

---

如果应使用枚举的 value，或者出于任何原因必须翻转枚举键和值 ，我会使用

valueOf<T>

帮助器。缺点是，这在 VSCode 中不提供自动完成功能。但至少函数参数定义在某种程度上是可读的。

/**
 * @typedef {T[keyof T]} valueOf<T>
 * @template T
 */

const TYPES = {
    "TYPE_A": 0,
    "TYPE_B": 1
};

/**
 * @param {valueOf<TYPES>} type
 */
function useTypesEnum(type) {
    // ...
}

Answer 4

不幸的是，我发现的唯一方法是定义另一个

type

（

@typedef

）：

/**
 * @enum { number }
 */
const TYPES = {
    TYPE_A: 1,
    TYPE_B: 2
}

/** @typedef {'TYPE_A'|'TYPE_B'} TYPES_KEYS */

/**
 * @param { TYPES_KEYS } input
 */
function useTypesEnum(input) {
  // ...
}

Answer 5

解析对象时，Typescript 会将该对象的值转换为其通用版本 (

string

)，除非您专门覆盖它。您还可以使用

typeof

来纠正一些 Typescript 逻辑：例如：

const Animal = {
  CAT: /** @type {'cat'} */ ('cat'),
  DOG: /** @type {'dog'} */ ('dog'),
  WOLF: /** @type {'wolf'} */ ('wolf')
};

/** @typedef {Animal[keyof Animal]} AnimalValue */
/** @typedef {typeof Animal.DOG | typeof Animal.WOLF} BarkingAnimal */

/** @type AnimalValue */
let animal = Animal.CAT;
animal = Animal.DOG;
// @ts-expect-error: Type 'string' is not assignable to type '{ CAT: "cat"; DOG: "dog"; }'
animal = 'house';

/** @type BarkingAnimal */
let barker = Animal.DOG;
barker = 'wolf';
// @ts-expect-error: Type '"cat"' is not assignable to type 'BarkingAnimal'.
barker = Animal.CAT;

游乐场链接

是不是很冗长？是的。但这有效吗？另外，是的。

我仍在尝试找出一种让它变得更简单的方法，但这是一个开始。

Answer 6

JSDoc 注释对 JavaScript 代码没有影响。它真正影响的是一些旨在使用该信息的工具。使用 JSDoc 注释的两个工具是文档生成器和 Google Closure Compiler。

我对 JSDoc 3 不是特别熟悉，其中添加了

@enum

标签，但我认为它与任何其他类型一样工作。

闭包编译器还可以正确识别

enum

，您可以像示例中提到的那样使用它，并获得编译器的所有好处（例如：类型检查）。