Javascript + JsDoc: How to document new ES6 datatypes like map?

Question

I'm trying to use JSDoc in my ES6 project, I'm returning a Map:

/**
 * Some documentation.. 
 *
 * @returns {undefined} <- This should be replaced
 */
function returningMap() {
    const someMap = new Map();
    someMap.set("key", {a, b, c});
    return someMap;
}

How should I document this with @returns?

There is not good answer here.

I have a nearly similar problem. https://stackoverflow.com/questions/38309123/jsdoc-with-and-immutable-js-datastructures-in-annotations — Marcel Mandatory, Jul 12 '16 at 06:46

score 8 · Accepted Answer · answered Oct 01 '17 at 20:49

The answer is simple and beautiful:

/**
 * Some documentation.
 *
 * @return {Map<String, Object>}
 */
function returningMap() {
    const someMap = new Map();
    someMap.set("key", {a, b, c});
    return someMap;
}

The basic pattern is Map<KeyType, ValueType>. From your example, key would be a string and value an object. You could even go ahead and declare your object as well. For instance:

/**
 * @typedef {Object} MyObject
 * @property {Number} a
 * @property {Number} b
 * @property {String} c
 */

And then your map would be declared as Map<String, MyObject>. Cool, isn't, it? You could also nest other maps or even sets, like Map<Number, Set<MyObject>>.

Frank Tan · Answer 2 · 2016-07-18T23:56:15.387

Your best bet is probably to define Map and friends with @external somewhere:

/**
 * The Map object is a simple key/value map. Any value (both objects and primitive values) may be used as either a key or a value.
 * @external Map
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map}
 */

Then your type will be defined, so you can say @returns {Map} as the comments say.

A convenient place to get all the URLs and one-liners in one place is from tern.

Javascript + JsDoc: How to document new ES6 datatypes like map?

2 Answers2