Основной Агент Проверки

AI Агент по Проверке Документации

Держите вашу документацию синхронизированной с кодом

Устаревшая документация хуже, чем отсутствие документации — она активно вводит в заблуждение. Проверка Документации обнаруживает, когда изменения кода делают документацию неправильной.

Что Обнаруживает Проверка Документации

Тихие ошибки — документация, которая лжет

Устаревшая Документация

Документы, описывающие старое поведение — самый опасный вид документации

Устаревший READMEСтарые примеры APIДокументированные устаревшие параметры

Отсутствующая Документация API

Публичные функции и endpoints без надлежащей документации

Недокументированные экспортыОтсутствующие описания параметровНет документации типа возврата

Вводящие в Заблуждение Комментарии

Комментарии, которые говорят одно, а код делает другое — хуже, чем отсутствие комментариев

Устаревшие TODOНеправильные объясненияСкопированные комментарии

Несоответствие OpenAPI/Swagger

Документация API, которая не соответствует реальным endpoints — причина #1 ошибок интеграции

Неправильная схема ответаОтсутствующие endpointsУстаревшая документация аутентификации

Синхронизация Документации Компонентов

Документация Storybook и компонентов, которые не отражают изменения props

Отсутствующие свойстваНеправильные значения по умолчаниюУстаревшие примеры

Расхождение Определений Типов

Типы TypeDoc/JSDoc, которые не соответствуют реальным интерфейсам и сигнатурам

Опциональное отмечено как обязательноеНеправильные универсальные типыОтсутствующие типы объединения

Охватываемые Типы Документации

Каждое место, где документация и код могут рассинхронизироваться

JSDoc / TSDoc

Документация функций и методов

Файлы README

Обзоры проектов и пакетов

Встроенные комментарии

Объяснения кода и TODO

Документация API

Описания и примеры endpoints

Определения типов

Комментарии интерфейсов и типов

Записи Changelog

Точность истории версий

Уникальная Метрика

Оценка Задолженности по Документации

Как техническая задолженность, задолженность по документации накапливается молча. Мы даем вашей кодовой базе Оценку Здоровья Документации — одно число, которое показывает, насколько далеко отстает ваша документация от реальности.

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

Здоровье Документации

73/100

README.md

Последнее обновление 45 дней назад, код изменен 12 раз

src/api/

3 недокументированных endpoints

CHANGELOG.md

Отсутствуют записи для v2.3.0, v2.3.1

src/utils/

8 экспортированных функций без JSDoc

Тренд в этом месяце-5 баллов
Осведомлен о Фреймворках

Глубокое Понимание Фреймворков

Не просто общие проверки документации — мы понимаем паттерны документации вашего фреймворка

Next.js / React

  • Документация props компонентов
  • Примеры использования hooks
  • Описания route handlers
  • Документация middleware

NestJS / Express

  • Синхронизация декораторов Swagger
  • Документация DTOs
  • Документация методов контроллера
  • Описания модулей

FastAPI / Django

  • Docstrings моделей Pydantic
  • Описания endpoints
  • Схемы ответов
  • Документация query параметров

GraphQL

  • Описания схемы
  • Документация resolvers
  • Определения типов
  • Документация Mutation/Query
Предложение AI

Для функции processPayment(amount, currency, options):

/**
 * Обрабатывает транзакцию платежа
 * @param amount - Сумма в центах (целое число)
 * @param currency - Код валюты ISO 4217
 * @param options - Опции обработки
 * @param options.idempotencyKey - Уникальный ключ
 * @param options.metadata - Пользовательские пары ключ-значение
 * @returns Promise<PaymentResult>
 * @throws PaymentError если отклонен
 */
Работает на AI

Не Только Обнаружение — Генерация

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

Авто-Генерация JSDoc

Создает документацию на основе сигнатур функций и типов

Обновление Существующей Документации

Обновляет устаревшую документацию в соответствии с текущим кодом

Обнаружение Несоответствия Документации

Реальные примеры документации, которая требовала обновления

Устаревшая Документация Параметра

Устаревшее
/**
 * Получает пользователя по ID
 * @param id - ID пользователя
 * @param includeDeleted - Включить мягко удаленных пользователей
 */
async function getUser(id: string, options?: GetUserOptions) {
  // includeDeleted переместился в объект options 3 месяца назад
  // но JSDoc все еще показывает старую сигнатуру
}

JSDoc показывает старую сигнатуру с позиционным параметром

Обновленное
/**
 * Получает пользователя по ID
 * @param id - ID пользователя
 * @param options - Опции запроса
 * @param options.includeDeleted - Включить мягко удаленных пользователей
 * @param options.fields - Поля для выбора
 */
async function getUser(id: string, options?: GetUserOptions) {
  // Документация соответствует реальной сигнатуре
}

Обновлено в соответствии с текущим паттерном объекта options

Вводящий в Заблуждение Комментарий

Устаревшее
// Повтор 3 раза с экспоненциальной задержкой
async function fetchWithRetry(url: string) {
  const MAX_RETRIES = 5  // Изменено с 3
  const response = await fetch(url)
  // На самом деле логика повтора больше не реализована
  return response
}

Комментарий описывает логику повтора, которая не существует

Обновленное
// Простой обертка fetch, нет логики повтора
// Для повторов используйте fetchWithRetry из @/lib/http
async function simpleFetch(url: string) {
  const response = await fetch(url)
  return response
}

Комментарий отражает реальное поведение

Несоответствие README

Устаревшее
## Установка
```bash
npm install
npm run setup  # Этот скрипт был удален
```

## Переменные Окружения
- `DATABASE_URL` - Подключение PostgreSQL
- `REDIS_URL` - Подключение Redis  # Мы перешли на кэш в памяти

README ссылается на удаленный скрипт и старую конфигурацию Redis

Обновленное
## Установка
```bash
npm install
```

## Переменные Окружения
- `DATABASE_URL` - Строка подключения PostgreSQL
- `CACHE_TTL` - Продолжительность кэша в секундах (по умолчанию: 3600)

Документация отражает текущий процесс конфигурации

Семантический Анализ

Как Работает Проверка Документации

Проверка Документации не просто проверяет, существует ли документация — она проверяет, что она соответствует тому, что код действительно делает. Когда вы изменяете сигнатуру функции, она сообщает о JSDoc.

Семантическое Сопоставление

Сравнивает то, что говорит документация и что делает код

Обнаружение Изменений

Замечает, когда изменения кода делают соседнюю документацию неправильной

Предложения по Обновлению

Предоставляет конкретный текст для исправления документации

Конвейер Анализа

1

Сравнить Код и Документацию

Проверяет, соответствует ли документация реальной реализации

2

Обнаружить Изменения

Определяет, когда изменения кода делают существующую документацию неправильной

3

Сообщить о Несоответствиях

Информирует о документации, которая может ввести разработчиков в заблуждение

4

Предложить Обновления

Предоставляет конкретный текст для обновления документации

Почему Точность Документации Имеет Значение

Плохая документация стоит дороже, чем отсутствие документации

Более Быстрая Отладка

Точная документация означает, что разработчики не тратят часы на неправильные пути

Лучшая Интеграция

Новые разработчики могут доверять тому, что они читают, вместо того чтобы угадывать

Доверие к API

Пользователи могут доверять вашей документации API без проб и ошибок

Каждое изменение кода — это возможность для документации отстать.
Проверка Документации обнаруживает это каждый раз.

Задолженность по Документации Везде

Эти проблемы проходят незаметно каждый день — до сих пор

65%

файлов README устаревают в течение 6 месяцев

40%

комментариев JSDoc не соответствуют сигнатурам

3,2ч

среднее время потеряно на отладку из-за неправильной документации

80%

документации API отсутствует как минимум одно обязательное поле

Держите Документацию и Код
Синхронизированными

Позвольте Проверке Документации обнаружить несоответствие перед тем, как оно введет в заблуждение. Бесплатно на 14 дней, без кредитной карты.

Валидация JSDoc
Синхронизация README
Точность Комментариев