Can I reference a param type in JSDoc @return?

7
votes

I would like to document a function whose return type depends on the supplied parameter:

/**
* @param {*} x A thing
* @return {????} The thing in an array
*/
function arrayOf(x) { return [x]; }

Is it possible to name or otherwise reference the actual type of the function param, so that I can use it to specify the return?

2
javascriptjsdoc

2 Answers

9
votes

I commented on the other answer that what I'm looking for boils down to a generic parameter, which is implemented in JSDoc with @template. I don't know if it's part of core JSDoc -- I think it's a Closure extension -- but Typescript does recognize it if you're running your JS through TS, or just trying to get autocomplete working in your IDE.

Adapted from that link:

/**
 * @template T
 * @param {T} x - A generic parameter that flows through to the return type
 * @return {T[]}
 */
function id(x) {
  return [x];
}
1
votes

Don't know if there is a generic way to represent - this needs to be specified within the function description, but following could be the options:

For an elaborate description, might create a thing typedef:

/**
 * Thing Type
 * @typedef {*} thing
 */

/**
 * Returns a single element array encapsulating only the param value
 * @param {thing} x A thing
 * @return {thing[]} The thing in an array
 */
function arrayOf(x) { return [x]; }

else, simply,

/**
 * Returns a single element array encapsulating only the param value
 * @param {*} x A thing
 * @return {*[]} The thing in an array
 */
function arrayOf(x) { return [x]; }