Jsdoc: A method of documenting a predefined set of parameter values

[gajus]

From what I can tell, my research of the @type and Stack Overflow question, there is no standard way of documenting a set of predefined values that a parameter can have, e.g.

/**
 * @param {String} source
 */

Source parameter can have only two possible values: "youtube" and "vimeo". I want to document value type and give them a description.

I imagine that documenting a range of string values could look like something along the lines of:

/**
 * @typedef source
 * @enum
 * @value {"youtube"} youtube.com
 * @value {"vimeo"} vimeo.com
 */

/**
 * @param {source} source
 */

Equally, it could be used to describe a broader range of values and their types, e.g.

/**
 * @typedef source
 * @enum
 * @value {YouTubeType}
 * @value {VimeoType}
 */

/**
 * @param {source} source
 */

[gajus]

@hegemonic who should I be chasing to discuss this?

[gajus]

Another example. I am using this invented syntax to describe https://github.com/gajus/react-youtube-player component.

/**
 * @typedef {String} YoutubePlayer~playbackState
 * @value 'unstarted' Stops and cancels loading of the current video. [stopVideo]{@link https://developers.google.com/youtube/iframe_api_reference#stopVideo}
 * @value 'playing' Plays the currently cued/loaded video. [playVideo]{@link https://developers.google.com/youtube/iframe_api_reference#playVideo}
 * @value 'paused' Pauses the currently playing video. [pauseVideo]{@link https://developers.google.com/youtube/iframe_api_reference#pauseVideo}
 */

/**
 * @property {String} videoId
 * @property {String|Number} width (default: '100%').
 * @property {String|Number} height (default: '100%').
 * @property {YoutubePlayer~playbackState} playbackState
 */

[vekexasia]

Indeed this is pretty useful +1

[tcomert]

+1, I would like to see this as well

[catx23]

can somebody please confirm that jsdoc just doesn't support enums despite its show an enumeration in the docs but its not creating links to that enum for param. I tried all day long and have no result, nada, not even close.

[Jacse]

Great suggestion. Would be great to have a way of declaring custom enums regardless of actual implementation like a @typedef for enums. That would also enable one to do the following in a module:
````
/**

• @typedef {String} errorTypes
• @enum
• @value 'CRITICAL_ERROR'
• @value 'NETWORK_ERROR'
  */
  export const CRITICAL_ERROR = 'CRITICAL_ERROR';
  export const NETWORK_ERROR = 'NETWORK_ERROR';
  ````

I'm not sure if that is already achievable in current JSDoc version, but I certainly haven't been able to get it working. Not sure what the syntax should look like though.

[byterider]

Why not something simple like
@param {string="value1","value2"}
like these guys use: http://apidocjs.com/#param-api-param

[noodle71]

+1

[ghost]

+1 as well

[shikaan]

How far is this Future?

[tehpsalmist]

Are we all just writing weird javascript, or are there just bigger fish to fry? I'm a little perplexed as to why this isn't a feature yet, since it was suggested 3 years ago now. Don't want to seem unappreciative, just not sure why this particular feature hasn't seen much progress in that timeframe.

[tehpsalmist]

FWIW, when working with strings, this works like a dream:

@type {'firstoption' | 'secondoption' | 'thirdoption'}
or even
@param {'firstoption' | 'secondoption' | 'thirdoption'}

I don't know if doing that will answer everyone's angst in this thread, but it was a gamechanger for me.

[jerroydmoore]

Perhaps the docs should have these kinds of examples? Though, I'd love to be able to add annotations to each value: why would you choose _firstoption_ over _secondoption_?

[bennypowers]

Perhaps the docs should have these kinds of examples? Though, I'd love to be able to add annotations to each value: why would you choose _firstoption_ over _secondoption_?

Not exactly what you're going for, but you can

/**
 * @param {'red' | 'blue | 'green'} arg colour value. red for stop, green for go, blue for go, but in Japanese.
 */
const lights = color =>
    color === red ? stop()
  : color === blue ? go()
  : color === green ? go({japanese: true})
  : null

[mliq]

Thanks @tehpsalmist, but that doesn't work in the case of using an enum.

For example:

const ENUM = {
    FIRST: 'firstoption'
};

/**
 * @param {'firstoption' }
 */
function myFunc(var) {}

myFunc(ENUM.FIRST);

VSCode / Typescript throws:
Argument of type 'string' is not assignable to parameter of type '"firstoption"'. ts(2345)