80

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?

2
  • 1
    Did you try? What happened?
    – Xotic750
    Commented Feb 11, 2014 at 13:02
  • Yes, but only in jsfiddle. It works, also if I use TYPESSS for @param.
    – BuZZ-dEE
    Commented Feb 11, 2014 at 13:22

6 Answers 6

133

You can achieve that, by doing this:

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

}

enter image description here

11
  • 4
    Thank you very much, this was what I was looking for and should be the accepted answer
    – 66h3m3ab
    Commented Sep 22, 2020 at 3:26
  • 1
    I couldn't tell you how you made my day, Leuan! Commented Sep 22, 2020 at 11:21
  • 1
    Could that be combined with @typedef ?
    – jakubiszon
    Commented May 20, 2021 at 23:18
  • 11
    for me this worked: @param {'choice1'|'choice2'} type
    – tehmas
    Commented Jul 12, 2021 at 7:04
  • 2
    What if, at some point, the underlying enumeration changes? Commented May 4, 2022 at 10:07
69

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"
    */
2
  • 4
    This solution results in MyType being number. This will ensure that you're sending something that is the same type as the enum's values, but it won't raise errors if you pass unknown values. useTypesEnum( 3 ) would not raise an error here, but should.
    – Mark
    Commented Mar 2, 2022 at 18:37
  • This does not restrict the possible values Commented Aug 13, 2023 at 10:06
15

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.

Suggestion screenshot


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) {
    // ...
}

Suggestion 2 screenshot

4
  • 3
    The most useful and type-safe answer that is up-to-date. If values require stricter matching, supposed object enum can be type cast to readonly via /** @type {const} */ ({ 0: "TYPE_A", 1: "TYPE_B" }), but yeah it's too verbose.
    – vintprox
    Commented Dec 13, 2022 at 11:02
  • It also works if TYPES is a module, imported as import * as someEnum from ''some-enum.js'.
    – Hibou57
    Commented Mar 13, 2023 at 13:07
  • This is typescript, not pure jsdoc Commented Aug 13, 2023 at 10:06
  • 1
    You may want to use Object.freeze around the TYPES object to make it a Readonly object -- this has the additional benefit that nonexistent enum entry will be flagged as error if you have type check on.
    – Zhe
    Commented Aug 28 at 3:01
5

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) {
  // ...
}
1
  • 1
    This is cumbersome, but it's also the only way I found (I came here looking for a better way, unfortunately none so far) Commented Aug 13, 2023 at 10:07
0

When parsing an object, Typescript will convert the value of that object into its generic version (string) unless you override it specifically. You can also use typeof as well to correct some Typescript logic: For example:

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;

Playground Link

Is it verbose? Yes. But does it work? Also, yes.

I'm still trying to figure out a way to make it simpler, but it's a start.

For more repeatable structure you can do:

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

/** @typedef {EnumOf<Animal>} AnimalEnum */
1
  • The @type thing (constness) can be achieved by adding Object.freeze around the object -- making it a Readonly object in TypeScript.
    – Zhe
    Commented Aug 27 at 10:01
-8

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).

2
  • no, it doesnt create links to that enum, only to typedefs.
    – xamiro
    Commented Feb 28, 2016 at 0:18
  • 3
    I don't see how the requestor inferred that the comments would impact the code, instead, they wanted to know how to influence their IDE's type hint logic. What they seem to have requested was whether identifying enums in jsdoc was possible, and if so, what the syntax was, which your answer does not seem to help with. I will admit that their question could have been stated better though.
    – Jitsusama
    Commented Jan 22, 2021 at 14:50

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.