VSCode: как документировать обещание, которое разрешается с помощью сложного объекта?

У меня есть функция f, которая возвращает a Promise. Возвращаемый Promise либо resolve({name: String, data: Object}), либо reject(Error).

Я пробовал следующий синтаксис (как упоминалось в проблема в JSDoc) в VSCode, но он не работает:

/**
 * @promise fPromise
 * @reject {Error}
 * @fulfill {Object} project
 * @fulfill {Object} project.data
 * @fulfill {String} project.name
 * @returns fPromise
*/

Ответ 1

Думаю, лучше всего заключить ваш ответ fulfill в пользовательский объект:

/**
 * @promise fPromise
 * @reject {Error}
 * @fulfill {Project}
 * @returns {Promise.<Project>}
*/
function renderResults(data) {
    return new Promise((resolve, reject) => {
        resolve(new Project())
    })
}

renderResults()

function Project() {
    this.data = "data";
    this.name = "project phoenix"
    this.location = {
        city: 'seattle',
        state: 'wa'
    }
}

Это будет показано в VS-коде, как показано ниже:

Ответ 2

Чтобы быть как можно более ясным, почему бы не поместить природу объекта в одну строку для описания? Его просто должно быть описание этого.

/**
 * @promise fPromise
 * @fulfill {Object} A project object with the format {name: String, data: Object}
 * @reject {Error}
 * @returns fPromise
*/

Или, если вы хотите обрабатывать динамически сгенерированные ключи объектов, похожие на Руководство по стилю Google:

/**
 * @promise fPromise
 * @fulfill {Object.<String, Object>} 
 * @reject {Error}
 * @returns fPromise
*/

Это позволяет любому, кто читает ваш комментарий, понять, как выглядит возвращаемый объект, какие ключи и какой тип значения должен быть в каждом ключе.

Если вы не пытаетесь сказать, что он может вернуть любую из трех возможностей. Тогда я думаю, что ваш оригинальный формат немного более подробно описывает возможные результаты выполнения обещания.