Описание структуры "объекта" в 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
Повышайте уровень своих знаний, используя материалы в разделе Полезные материалы.
Полезные материалы
- Используйте JSDoc: Введение в JSDoc 3 — Руководство и советы по работе с JSDoc.
- TypeScript: Документация JSDoc — Информация о синтаксисе JSDoc в контексте TypeScript.
- Учебник по JSDoc — Руководство по использованию тега @param.
- Шпаргалка по JSDoc — Напоминания о ключевых элементах JSDoc.
- Вопросы о JSDoc на Stack Overflow — Обсуждения и советы по работе с JSDoc.
- GitHub – jsdoc/jsdoc — Официальный репозиторий JSDoc, полезные исходники и обсуждения.