Перечислите как тип @param в JSDoc

Question

Можно ли использовать перечисление для JSDoc @param объявление типа, как в следующем примере?

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

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

}

Если я использую IDE, например, Eclipse и т. Д. Для JavaScript, не должно быть никакого предупреждения?

Answer 1

Комментарии JsDoc не влияют на код JavaScript. На это действительно влияют некоторые инструменты, предназначенные для использования этой информации. Двумя инструментами, которые работают с комментариями JsDoc, являются генератор документации и Google Closure Compiler.

Я не особенно знаком с JsDoc3, в котором был добавлен тег @enum, но я бы предположил, что он работает так же, как и любой другой тип.

Закрывающий компилятор также правильно распознает перечисление, и вы можете использовать его, как вы упомянули в примере, и получить все преимущества компилятора (например, проверка типов).

Answer 2

Вы можете добиться этого, сделав следующее:

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

}

Answer 3

Таким образом, кажется, что это правильный способ документировать все без предупреждения

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


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

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

}

Это означает:

• MyType - это число
• TYPES - это перечисление, которое содержит значения MyType
• Эта функция принимает перечисления, которые выводят значения MyType

У меня работает на интеллигент 2017.1

Тем не менее, это все равно позволит передавать каждую строку в функцию без предупреждений.

Если вы также хотите указать значения перечисления - поэтому он должен вызывать ошибки при использовании другой строки, используйте метод, описанный по адресу: /questions/12108975/kak-ispolzovat-jsdoc3-dlya-dokumentirovaniya-konstant-enum/12108984#12108984

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

Я использую следующее:

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

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

Это показывает правильные значения в качестве предложения в VSCode. Он легко читается, дает разработчикам представление о том, какое значение что представляет, а значения перечисления можно использовать во время выполнения.

---

Если мне не нужны значения во время выполнения, я даже предпочитаю использоватьTYPESкак@typedef:

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

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

---

Если необходимо использовать значение перечисления или ключи и значения перечисления должны быть перевернуты по какой-либо причине, я используюvalueOf<T>помощник. Недостатком является то, что это не предлагает автозаполнение в VSCode. Но, по крайней мере, определение параметра функции в какой-то степени читабельно.

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

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

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

Answer 5

К сожалению, единственный способ, который я нашел, - это определить другой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) {
  // ...
}