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?
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:
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"
*/
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) {
// ...
}
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) {
// ...
}
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).
The technical post webpages of this site follow the CC BY-SA 4.0 protocol. If you need to reprint, please indicate the site URL or the original address.Any question please contact:yoyou2525@163.com.