Работа с документацией

Как устроена документация

Документация состоит из двух частей:

1. Руководство (docs/guide/) — страницы, написанные вручную. Описывают концепции, паттерны и процессы.
2. API Reference (docs/api/) — страницы, сгенерированные автоматически из JSDoc комментариев в исходном коде.

Технологии

• VitePress — генератор статического сайта на основе Vue и Vite
• vitepress-jsdoc — генерирует markdown-страницы из JSDoc комментариев (CLI mode)
• vitepress-sidebar — автоматически строит sidebar из файловой структуры docs/api/

Структура файлов

docs/
├── .vitepress/
│   └── config.mjs              # Конфиг VitePress (nav, sidebar, base URL)
├── index.md                    # Лендинг (hero + features)
├── guide/                      # Вручную написанные страницы
│   ├── getting-started.md
│   ├── configuration.md
│   ├── services-overview.md
│   ├── models-overview.md
│   ├── development.md
│   └── documentation.md
└── api/                        # Автогенерация (в .gitignore!)
    ├── config.md
    ├── services/*.md
    ├── models/*.md
    ├── mappers/*.md
    └── utils/*.md

WARNING

Папка docs/api/ перегенерируется при каждом запуске docs:gen. Файлы, для которых исходник содержит тег @module, будут перезаписаны. Файлы без @module в исходнике защищены от перезаписи (см. Защита от перезаписи).

Скрипты

Команда	Назначение
npm run docs:dev	Локальная разработка с hot-reload (запускает VitePress dev-сервер и watcher JSDoc одновременно)
npm run docs:gen	Генерация markdown из JSDoc (без сборки сайта)
npm run docs:build	Полная сборка: генерация + билд статического сайта в public/
npm run docs:preview	Предпросмотр собранного сайта

Локальная разработка

npm run docs:dev

Откроется dev-сервер (обычно на http://localhost:5173). Изменения в guide-страницах и JSDoc комментариях подхватываются автоматически.

Редактирование руководства

Страницы руководства — обычные markdown-файлы в docs/guide/. Поддерживается весь синтаксис VitePress:

• Стандартный Markdown (заголовки, списки, таблицы, код)
• Контейнеры для заметок и предупреждений:

  ::: tip Совет
  Текст подсказки
  :::
  
  ::: warning Внимание
  Текст предупреждения
  :::

• Блоки кода с подсветкой синтаксиса и выделением строк

Добавление новой страницы

1. Создайте файл docs/guide/my-page.md
2. Добавьте запись в sidebar в docs/.vitepress/config.mjs:

   sidebar: {
     '/guide/': [
       {
         text: 'Руководство',
         items: [
           // ...существующие страницы
           { text: 'Моя страница', link: '/guide/my-page' },
         ],
       },
     ],
   }

Обновление API Reference

API Reference генерируется из JSDoc комментариев в исходном коде (src/). Чтобы обновить документацию API:

1. Убедитесь, что в начале файла есть тег @module (см. ниже)
2. Добавьте или обновите JSDoc комментарии в исходном файле
3. Запустите npm run docs:gen или npm run docs:dev
4. Сгенерированный markdown появится в docs/api/

Тег @module

Для того чтобы vitepress-jsdoc распознал файл и сгенерировал из него документацию, первой строкой файла должен быть тег @module:

/** @module clientService */
import { getAxios, getHost, notify } from '../config.js'

class ClientService {
  // ...
}

Без этого тега vitepress-jsdoc пометит файл как EMPTY и создаст пустышку (только заголовок).

Когда добавлять @module

Добавляйте @module только в файлы, которые содержат JSDoc комментарии к методам/функциям. Если в файле нет JSDoc — тег @module не имеет смысла, и документацию для него нужно писать вручную в docs/api/.

Защита от перезаписи

Скрипт docs:gen использует wrapper (scripts/docs-gen.cjs), который защищает вручную написанные doc-файлы от перезаписи пустышками.

Логика работы:

1. Перед запуском vitepress-jsdoc скрипт проверяет каждый исходный файл на наличие тега @module
2. Если @module есть — vitepress-jsdoc сгенерирует полноценную документацию, файл будет перезаписан
3. Если @module нет, а doc-файл уже существует и содержит контент — файл сохраняется в памяти и восстанавливается после генерации

Это позволяет безопасно писать документацию вручную для файлов без JSDoc (например, модели) и не терять её при перегенерации.

Формат JSDoc

Для функций и мапперов:

/**
 * Описание функции на русском
 * @param {Object} data - Данные из API
 * @returns {Object} Трансформированные данные
 */
export function myMapper(data) { ... }

Для методов сервисов (ES6 классы):

class MyService {
  /**
   * Описание метода
   * @param {{ key1: string, key2: number }} params - Параметры запроса
   * @param {Function} [mapper] - Опциональный маппер
   * @returns {Promise<Object|null>} Данные или null при ошибке
   */
  async GetTable(params, mapper) { ... }
}

JSDoc и парсер

Парсер JSDoc (используемый vitepress-jsdoc) не поддерживает TypeScript-синтаксис в типах. Избегайте:

• import('module').Type — используйте Object или @typedef
• { key?: string } (optional с ?:) — используйте { key: string } или разделяйте на отдельные @param

Поддерживаемые теги

Тег	Пример	Описание
@module	@module clientService	Объявление модуля (обязательно для автогенерации)
@param	@param {string} id	Параметр функции
@returns	@returns {Object}	Возвращаемое значение
@example	@example myFunc('test')	Пример использования
@typedef	@typedef {Object} MyType	Определение типа
@deprecated	@deprecated Используйте newFunc	Устаревший метод
@alias	@alias module:clientService	Привязка класса к модулю (см. ниже)
@private	@private	Приватный метод (исключается из документации)

@alias и классы

Тег @module объявляет модуль, но JSDoc-парсер не привязывает к нему методы ES6-классов автоматически. Чтобы методы класса отображались в документации как методы модуля, перед классом нужно добавить @alias:

/** @module clientService */
import { getAxios, getHost, notify } from '../config.js'

/** @alias module:clientService */
class ClientService {
  /**
   * Получает данные клиента по ID
   * @param {string} id - ID клиента
   * @returns {Promise<Object|null>} Данные клиента или null
   */
  async GetById(id) { ... }
}

export const clientService = new ClientService()

Без @alias: парсер не свяжет GetById с модулем clientService. В документации появится страница модуля, но без методов.

С @alias module:clientService: парсер поймёт, что методы ClientService принадлежат модулю clientService, и отобразит их на странице модуля.

Правило

Каждый сервис-класс должен иметь @alias module:<имяМодуля> перед объявлением класса, где <имяМодуля> совпадает с @module в начале файла.

Деплой

Документация автоматически собирается и публикуется на GitLab Pages при пуше в ветку develop.

Pipeline определён в .gitlab-ci.yml:

1. npm ci — установка зависимостей
2. npm run docs:build — генерация JSDoc markdown + сборка VitePress
3. Артефакт public/ публикуется как GitLab Pages

Доступ к документации ограничен участниками проекта (настройка в GitLab: Settings → General → Pages → "Only project members").

Конфигурация VitePress

Основной конфиг: docs/.vitepress/config.mjs

Ключевые параметры:

Параметр	Значение	Описание
base	'/frontend.npm.serviceslibrary/'	Базовый путь URL на GitLab Pages
outDir	'../public'	Директория билда (для GitLab Pages)
lang	'ru-RU'	Язык сайта
search.provider	'local'	Встроенный полнотекстовый поиск