|
JSDoc это стандартный язык разметки для документирования JavaScript-кода прямо в комментариях. Он не только помогает создавать понятную документацию, но и значительно улучшает процесс разработки, обеспечивая автодополнение и подсказки в редакторах кода.
[Основы синтаксиса JSDoc]
Документирование строится на специальных комментариях, которые начинаются с `/**` и закрываются `*/`. Такой комментарий помещается непосредственно перед объявляемой функцией, классом или переменной.
Базовая структура для функции. Самый простой пример включает описание, тег `@param` для параметра и тег `@returns` (или `@return`) для возвращаемого значения.
/**
* Складывает единицу с переданным числом.
* @param {number} input Любое число.
* @returns {number} Входное число, увеличенное на единицу.
*/
function addOne(input) {
return input + 1;
}
Разберем элементы:
`@param {number} input any number` — тег, указывающий на параметр. В фигурных скобках задается тип (`number`), после них — имя параметра (`input`) и его описание.
`@returns {number} that number, plus one.` — тег, описывающий возвращаемое значение. Также указывается тип и описание.
[Ключевые теги JSDoc]
Вот основные теги, которые чаще всего используются при документировании функций:
| Тег |
Назначение |
Пример |
| `@param` |
Описывает параметр функции. Можно указать тип, имя и описание. Для необязательных параметров используется синтаксис с квадратными скобками `[param]` или `[param=значение]` для значения по умолчанию. |
`@param {string} [name="Гость"] Имя пользователя.` |
| `@returns` или `@return` |
Описывает возвращаемое значение. |
`@returns {boolean} Результат проверки.` |
| `@example` |
Показывает пример использования функции. Этот блок будет красиво отформатирован в сгенерированной документации. |
`@example const result = addOne(5); // 6` |
| `@private` |
Помечает функцию как приватную. Она не будет включена в публичную документацию. |
`@private` |
| `@deprecated` |
Указывает, что функция устарела и её не рекомендуется использовать. |
`@deprecated` |
| `@overload` |
Используется для документирования функций с несколькими возможными сигнатурами (перегрузками), когда набор параметров зависит друг от друга. |
См. пример ниже. |
Пример с необязательным параметром:
/**
* Приветствует пользователя.
* @param {string} [name="Stranger"] Имя пользователя.
* @returns {string} Приветствие.
*/
function sayHello(name) {
name = name || "Stranger";
return `Hello, ${name}!`;
}
Пример с перегрузкой (`@overload`):
/**
* @overload
* @param {string} name Имя свойства для получения.
* @returns {string} Значение свойства. */
/**
* @overload
* @param {number} index Индекс элемента.
* @returns {object} Объект элемента.
*/
function get(arg) {
// Реализация функции...
}
Такой подход позволяет редактору кода предлагать корректные подсказки в зависимости от типа переданного аргумента.
[Расширенные возможности и интеграция]
Типы данных. JSDoc поддерживает не только примитивные типы (`string`, `number`). Вы можете описывать сложные структуры:
Объединенные типы (Union Types): используйте `|` для указания, что параметр может быть одного из нескольких типов: `{number|string}` или `{number|number[][]}` для двумерного массива чисел.
Объекты (Object): можно описать структуру объекта как в виде `{ { a: string, b: number } }`, так и с помощью тега `@typedef` для создания пользовательских типов.
/**
* @typedef {Object} User
* @property {string} name Имя пользователя.
* @property {number} age Возраст пользователя.
*/
/**
* @param {User} user Объект пользователя.
*/
function printUser(user) { /* ... */ }
[Инструменты и среда разработки]
Генерация документации: утилиты вроде documentation.js могут прочитать ваши JSDoc-комментарии и создать из них готовый HTML-сайт или Markdown-файл с документацией.
Редакторы кода: современные IDE (IntelliJ IDEA, VS Code) автоматически распознают JSDoc. При вводе `/**` и нажатии Enter они генерируют заготовку со всеми тегами, а при вызове функции показывают всплывающие подсказки с вашими комментариями .
TypeScript: вы можете использовать синтаксис TypeScript для указания типов прямо внутри JSDoc-комментариев (`@type`, `@typedef`, `@template`). Это позволяет добавлять строгую типизацию в обычные JavaScript-файлы.
[Важный нюанс для Google Apps Script]
Если вы пишете пользовательские функции для Google Sheets, помните о следующих особенностях:
● Для появления функции в списке формул обязательно используйте тег `@customfunction`.
● Описание из тега `@return` не отображается в всплывающей подсказке Google Sheets.
● Синтаксис для необязательных параметров (`[param]`) и значений по умолчанию (`[param=value]`) не поддерживается в пользовательском интерфейсе Google Sheets — все параметры будут отображаться как обязательные.
|
