Enum como tipo @param en JSDoc

¿Es posible usar una enumeración para el JSDoc? @param declaración de tipo como en el siguiente ejemplo?

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

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

Si uso un IDE como Eclipse, etc. para JavaScript, ¿no debería aparecer ninguna advertencia?

Puedes lograr eso, haciendo esto:

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

}

Entonces parece que esta es la forma correcta de documentar todo sin previo aviso.

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


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

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

}

Esto significa:

• MiTipo es un número
• TYPES es una enumeración que contiene valores MyType
• Esta función acepta enumeraciones que generan valores MyType

Funciona para mí en intellij 2017.1

Sin embargo, esto aún permitirá que cada cadena se pase a la función sin advertencias.

Si también desea especificar los valores de enumeración, por lo que debería generar errores si se usó otra cadena, use el método descrito en: 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"
    */

Yo uso lo siguiente:

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

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

Esto muestra los valores correctos como sugerencia en VSCode. Es muy legible, brinda a los desarrolladores una pista sobre qué valor representa qué y los valores de enumeración se pueden usar en tiempo de ejecución.

Si no necesito los valores de TYPES en tiempo de ejecución, incluso prefiero usar el TYPES como un @typedef:

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

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

Si el valor de la enumeración debe usarse, o las claves y valores de enumeración debe ser volteado por cualquier razón, yo uso el valueOf<T> ayudante. La desventaja es que esto no ofrece autocompletado en VSCode. Pero al menos la definición de parámetros de funciones es, hasta cierto punto, legible.

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

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

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

Desafortunadamente, la única forma que encontré es definir otra 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) {
  // ...
}

Los comentarios de JSDoc no tienen impacto en el código JavaScript. Lo que sí influye son algunas herramientas diseñadas para usar esa información. Dos de las herramientas que funcionan con los comentarios de JSDoc son el generador de documentación y el compilador de cierre de Google.

No estoy particularmente familiarizado con JSDoc 3, en el que el @enum Se ha agregado la etiqueta, pero supongo que funciona como cualquier otro tipo.

Closure Compiler también reconoce el enum correctamente y puede usarlo tal como lo mencionó en el ejemplo y obtener todos los beneficios del compilador (por ejemplo, verificación de tipo).