Enum as @param type in JSDoc

Question

Is it possible to use an enum for the JSDoc @param type declaration like in the following example?

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

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

If I use an IDE like Eclipse etc. for JavaScript, there should no warning be raised?

Answer 1

You can achieve that, by doing this:

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

}

Answer 2

So it seems this is the right way to document everything without any warning

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


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

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

}

This means:

• MyType is a number
• TYPES is an enum that holds MyType values
• This function accepts enums that output MyType values

Works for me on intellij 2017.1

However - this will still allow each string to be passed to the function without warnings.

If you want to specify the enum values too - so it should raise errors if another string was used, use the method described at: 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

I use the following:

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

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

This shows the correct values as a suggestion in VSCode. It is nicely readable, gives developers a clue about which value represents what and the enum values can be used in runtime.

---

If I do not need the values of TYPES in runtime, I even prefer to use the TYPES as a @typedef:

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

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

---

If the value of the enum should be used, or the enum keys and values must be flipped for any reason, I use the valueOf<T> helper. The downside is, that this does not offer auto-completion in VSCode. But at least the functions parameter definition is, to some extent, readable.

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

Unfortunately, the only way I found is to define another 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

JSDoc comments have no impact on JavaScript code. What it does influence is some tools designed to use that information. Two of the tools that work with JSDoc comments are the documentation generator and the Google Closure Compiler.

I am not particularly familiar with JSDoc 3, in which the @enum tag has been added, but I would assume it works just as any other type.

The Closure Compiler also recognizes the enum correctly and you can use it just like you mentioned in the example and get all the benefits of the compiler (ex: type checking).