Enum as @param type in JSDoc

问题

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?

回答1:

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 JsDoc3, 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:

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

回答3:

You can achieve that, by doing this:

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

}

来源：https://stackoverflow.com/questions/21702556/enum-as-param-type-in-jsdoc

标签

javascript

ide

jsdoc

jsdoc3