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 }
 */
var 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?

Solution 1

You can achieve that, by doing this:

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

}

Solution 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"
    */

Comments

[Xotic750]

Did you try? What happened?

[BuZZ-dEE]

Yes, but only in jsfiddle. It works, also if I use TYPESSS for @param.

[guy mograbi]

Did you ever solve this?

[xamiro]

no, it doesnt create links to that enum, only to typedefs.

[Ieuan]

Thank you very much, this was what I was looking for and should be the accepted answer

[Ahmed Mahmoud]

I couldn't tell you how you made my day, Leuan!

[Jitsusama]

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.

[jakubiszon]

Could that be combined with @typedef ?

[Ahmed Mahmoud]

@jakubiszon, yes. Just replace (1|2) with your custom type

[jakubiszon]

@AhmedMahmoud could I see an example of this? VSCode doesn't seem to pick it up when I do /** @typedef {(1|2)} testEnum */ When I reference it, it understands the type is testEnum but it doesn't suggest the values.

[Ahmed Mahmoud]

It works for me: imgur.com/a/yz9MHk7. Let me know if you tried the same and didn't work for you.

[tehmas]

for me this worked: @param {'choice1'|'choice2'} type

[Mark]

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.

[Davide Vitali]

What if, at some point, the underlying enumeration changes?