Как правильнее описать объект в JSDoc

Question

Как мне правильно описать данную функцию?

/**
 * Allows to search posts on user or community walls.
 * @param {Object} params
 * @property {string} params.domain user or community screen name
 * @property {number} params.owner_id user or community id
 * @property {string} params.querry search query string
 * @property {number} [params.count=1] 1 – returns only page owner's posts (1 default, either 1 or 0)
 * @property {number} [params.ownersOnly=1] count of posts to return (1 default, either 1 or 0)
 * @property {number} [params.offset=0] results offset (0 default)
 * @property {number} [params.extended] show extended post info (either 1 or 0)
 * @property {string} [params.fields] list of comma-separated words
 * @returns {Promise} JSON Response
 */
async search(params)
{
    // ...
}

На данный момент вот так показывается подсказка:

Если вместо @property использовать @params, то выглядит куда лучше, но нет описания и не показывается значение по умолчанию (должно ли вообще?):

Используемый редактор - VSCode.

Answer 1

Здраствуйте можете указать @type {Object} params

Подробнее есть описание в этом посте How to describe “object” arguments in jsdoc?

Answer 2

Как мне правильно описать данную функцию?

Предложу такой вариант описания... Сначала описывается объект. Потом параметру функции можно будет указать описанный тип.

/**
 * * @typedef {Object} Params - Схема Params
 * @property {string} domain - user or community screen name
 * @property {number} owner_id - user or community id
 * @property {string} querry - search query string
 * @property {number} [count=1] - 1 returns only page owner's posts (1 default, either 1 or 0)
 * @property {number} [ownersOnly=1] - count of posts to return (1 default, either 1 or 0)
 * @property {number} [offset=0] - results offset (0 default)
 * @property {number} [extended] - show extended post info (either 1 or 0)
 * @property {string} [fields] list of comma-separated words
 */


/**
 * Allows to search posts on user or community walls.
 * @param {Params} params
 * @returns {Promise} JSON Response
 */
async function search(params){
    // ...
}

БЛОГ НА HUSL

Как правильнее описать объект в JSDoc

Ответы (2 шт):