Описание структуры "объекта" в JSDoc: требуемые и опциональные поля

Быстрый ответ

Для правильного оформления параметра типа object в JSDoc следует использовать подход, представленный ниже:

/**
 * Осуществляет установление безопасной связи, аналогично секретному рукопожатию.
 * @param {Object} options — Загадочный объект настроек.
 * @param {string} options.url — Место сбора, в данном контексте это URL.
 * @param {number} [options.timeout=5000] — Период ожидания перед отступлением, указывается в миллисекундах, является необязательным.
 */
function initConnection(options) {
  // А вот и начинается шпионский марш-бросок...
}

Тег @param дает возможность описать свойства объекта, такие как обязательный url и необязательный timeout со значением по умолчанию в 5000 мс. Необязательные параметры обозначаются с помощью квадратных скобок, а их типы — с использованием фигурных.

Подробное описание документирования объектных аргументов

Совершенствуйте качество JSDoc-документации для объектных аргументов с помощью следующих советов. Таким образом, ваш код станет понятным и удобным для использования.

@typedef: Разработка пользовательских типов

В случае работы со сложными объектами рекомендуется создавать пользовательские типы посредством @typedef и применять их там, где это нужно. Этот метод напоминает вызов надежного союзника.

/**
 * @typedef {Object} ConnectionOptions
 * @property {string} url – Адрес для предотвращения потери ориентации.
 * @property {number} [timeout=5000] – Терпение бывает необходимым, однако его ресурсы — не бесконечны.
 */

/**
 * Инициирует решительную сессию взаимосвязей в интернете.
 * @param {ConnectionOptions} options – Правила действий.
 */
function initialize(options) {
  // Ваш код раскрывает всю сущность...
}

Подробнее об этом расскажет наш спикер на видео

Указание опциональных свойств

Опциональные свойства следует обозначать квадратными скобками либо допишите |undefined к типу, как будто вы спрашиваете у заказчика: "Предпочитаете ли вы добавить картошку фри?".

/**
 * @param {{ url: string, [timeout]: number | undefined }} options – Варианты для выбора.
 */

Документирование вложенных свойств

В случае вложенных объектов организуйте теги @param или создайте новые @typedef для обеспечения ясности и простоты понимания.

/**
 * @param {Object} specs – Конфиденциальные данные устройства.
 * @param {string} specs.model – Модель или ключевое наименование.
 * @param {{ width: number, height: number }} specs.dimensions – Размеры устройства.
 */

Использование record-типов

При работе с анонимными объектами, имеющими определенный набор свойств, следует использовать record-типы. В данном случае имена не будут иметь значения!

/**
 * @param {Object.<string, number>} itemCounts – Совмещение названий товаров и их количества. Время для учета!
 */

Демонстрация использования объектов с помощью примеров

Для эффективного объяснения абстрактных концепций рекомендуется использовать примеры, которые успешно демонстрируют ожидаемый формат параметров.

/**
 * Распределяет обязанности между товарными запасами.
 * @param {Object.<string, number>} inventory – Отображение названий товаров в их функциях.
 * Пример:
 * {
 *   "apples": 50,
 *   "oranges": 20
 * }
 */

@return для описания возвращаемого объекта

Примените @return для описания структуры объекта, обеспечивающего возврат функции. Это по сути своей схема использования вашей функции.

/**
 * Запрашивает неклассифицированные данные профиля пользователя...
 * @return {{name: string, age: number}} Неклассифицированные данные профиля.
 */

Старайтесь делать комментарии в JSDoc максимально понятными и информативными!

Визуализация

Представим процесс документирования объекта, сравнив его с возведением 🏗 лесов:

/**
 * Возводит леса
 * @param {Object} options – Опции конструкции.
 * @param {string} options.type – Вид каркаса.
 * @param {Object} options.ladder – Характеристики лестницы.
 * @param {number} options.ladder.height – Высота над землей.
 * @param {boolean} options.ladder.hasSafetyRails – Есть ли ограждающие барьеры?
 */

Выступаете в роли архитектора в мире кода, поэтому делайте каждый элемент ясным.

Деструктуризация — работа с компонентами объекта

Добавьте деструктуризацию для простейшей обработки свойств. Это можно сравнить с разделением мебели от IKEA на составные части.

/**
 * Обрабатывает данные пользователя.
 * @param {Object} user – Типичный объект пользователя.
 * @param {string} user.name – Имя пользователя.
 * @param {number} user.age – Возраст в годах.
 */
function processUserData({ name, age }) {
  // Проводится поиск 'name' и 'age'...
}

Детальное описание обязательных и опциональных свойств

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

/**
 * Моделирует трансфигурацию настроек виджета.
 * @param {{requiredSize: string, optionalColor?: string}} config – Позволяет настроить размер и цвет.
 */

Самостоятельное обучение: Больше информации о JSDoc

Повышайте уровень своих знаний, используя материалы в разделе Полезные материалы.

Полезные материалы

1. Используйте JSDoc: Введение в JSDoc 3 — Руководство и советы по работе с JSDoc.
2. TypeScript: Документация JSDoc — Информация о синтаксисе JSDoc в контексте TypeScript.
3. Учебник по JSDoc — Руководство по использованию тега @param.
4. Шпаргалка по JSDoc — Напоминания о ключевых элементах JSDoc.
5. Вопросы о JSDoc на Stack Overflow — Обсуждения и советы по работе с JSDoc.
6. GitHub – jsdoc/jsdoc — Официальный репозиторий JSDoc, полезные исходники и обсуждения.