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 {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 — все параметры будут отображаться как обязательные.