Javascript + JsDoc: Как документировать новые типы данных ES6, такие как карта?

Question

Я пытаюсь использовать JSDoc в своем проекте ES6, я возвращаю карту:

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

Как я должен документировать это с @returns?

Здесь нет хорошего ответа.

Answer 1

Ответ прост и красив:

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

Основной шаблон Map<KeyType, ValueType>, Из вашего примера ключ будет строкой и значением объекта. Вы могли бы даже пойти дальше и объявить свой объект. Например:

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

И тогда ваша карта будет объявлена ​​как Map<String, MyObject>, Круто, не правда ли? Вы также можете вкладывать другие карты или даже наборы, например Map<Number, Set<MyObject>>,

Answer 2

Ваш лучший выбор, вероятно, определить Map и друзья с @external где-то:

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

Тогда ваш тип будет определен, так что вы можете сказать, @returns {Map} как говорится в комментариях.

Удобное место для получения всех URL-адресов и однострочников в одном месте - от tern.

Answer 3

В случае предопределенных ключей карты вы также можете использовать «@typedef» в качестве перечисления списка ключей и [неитерируемый] «Запись» вместо [итерируемый] «Карта».

      /**
 * @typedef {'AE' | 'BE' | 'BG'} BUILDING_TAG
 */
/**
 * Buildings
 * @type {Record<BUILDING_TAG, {name:string}>}
 */
const BUILDINGS = {
    'A' : { name: 'Building А' },
    'B' : { name: 'Building B' },
    'C' : { name: 'Building C' }
};

/**
 * @typedef {'SNR' | 'ELTEX' | 'TPLINK'} SWITCH_TYPE
 */
/** 
 * @typedef SWITCH
 * @property {string} ipAddress
 * @property {SWITCH_TYPE} type
*/

/** @type { {switches: Record<BUILDING_TAG,SWITCH[]>, other: string} } */
var CONF = {
    switches: {
        'A': 
            [
                {ipAddress: '1.2.3.4', type: 'SNR'},
                {ipAddress: '1.2.3.5', type: 'SNR'}
            ],
        'B': 
            [
                {ipAddress: '1.2.3.4', type: 'ELTEX'}
            ],
        'C': 
            [
                {ipAddress: '1.2.3.4', type: 'TPLINK'}
            ]
    },
    other: "something important"
};