Тихие ошибки — документация, которая лжет
Документы, описывающие старое поведение — самый опасный вид документации
Публичные функции и endpoints без надлежащей документации
Комментарии, которые говорят одно, а код делает другое — хуже, чем отсутствие комментариев
Документация API, которая не соответствует реальным endpoints — причина #1 ошибок интеграции
Документация Storybook и компонентов, которые не отражают изменения props
Типы TypeDoc/JSDoc, которые не соответствуют реальным интерфейсам и сигнатурам
Каждое место, где документация и код могут рассинхронизироваться
Документация функций и методов
Обзоры проектов и пакетов
Объяснения кода и TODO
Описания и примеры endpoints
Комментарии интерфейсов и типов
Точность истории версий
Как техническая задолженность, задолженность по документации накапливается молча. Мы даем вашей кодовой базе Оценку Здоровья Документации — одно число, которое показывает, насколько далеко отстает ваша документация от реальности.
README.md
Последнее обновление 45 дней назад, код изменен 12 раз
src/api/
3 недокументированных endpoints
CHANGELOG.md
Отсутствуют записи для v2.3.0, v2.3.1
src/utils/
8 экспортированных функций без JSDoc
Не просто общие проверки документации — мы понимаем паттерны документации вашего фреймворка
Для функции processPayment(amount, currency, options):
/**
* Обрабатывает транзакцию платежа
* @param amount - Сумма в центах (целое число)
* @param currency - Код валюты ISO 4217
* @param options - Опции обработки
* @param options.idempotencyKey - Уникальный ключ
* @param options.metadata - Пользовательские пары ключ-значение
* @returns Promise<PaymentResult>
* @throws PaymentError если отклонен
*/Когда мы находим отсутствующую или устаревшую документацию, мы не просто это сообщаем — мы генерируем исправление. AI анализирует ваши сигнатуры функций, типы возврата и паттерны использования для предложения точной документации.
Создает документацию на основе сигнатур функций и типов
Обновляет устаревшую документацию в соответствии с текущим кодом
Реальные примеры документации, которая требовала обновления
/**
* Получает пользователя по 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
}Комментарий отражает реальное поведение
## Установка
```bash
npm install
npm run setup # Этот скрипт был удален
```
## Переменные Окружения
- `DATABASE_URL` - Подключение PostgreSQL
- `REDIS_URL` - Подключение Redis # Мы перешли на кэш в памяти
README ссылается на удаленный скрипт и старую конфигурацию Redis
## Установка
```bash
npm install
```
## Переменные Окружения
- `DATABASE_URL` - Строка подключения PostgreSQL
- `CACHE_TTL` - Продолжительность кэша в секундах (по умолчанию: 3600)
Документация отражает текущий процесс конфигурации
Проверка Документации не просто проверяет, существует ли документация — она проверяет, что она соответствует тому, что код действительно делает. Когда вы изменяете сигнатуру функции, она сообщает о JSDoc.
Сравнивает то, что говорит документация и что делает код
Замечает, когда изменения кода делают соседнюю документацию неправильной
Предоставляет конкретный текст для исправления документации
Сравнить Код и Документацию
Проверяет, соответствует ли документация реальной реализации
Обнаружить Изменения
Определяет, когда изменения кода делают существующую документацию неправильной
Сообщить о Несоответствиях
Информирует о документации, которая может ввести разработчиков в заблуждение
Предложить Обновления
Предоставляет конкретный текст для обновления документации
Плохая документация стоит дороже, чем отсутствие документации
Точная документация означает, что разработчики не тратят часы на неправильные пути
Новые разработчики могут доверять тому, что они читают, вместо того чтобы угадывать
Пользователи могут доверять вашей документации API без проб и ошибок
Каждое изменение кода — это возможность для документации отстать.
Проверка Документации обнаруживает это каждый раз.
Эти проблемы проходят незаметно каждый день — до сих пор
файлов README устаревают в течение 6 месяцев
комментариев JSDoc не соответствуют сигнатурам
среднее время потеряно на отладку из-за неправильной документации
документации API отсутствует как минимум одно обязательное поле
Позвольте Проверке Документации обнаружить несоответствие перед тем, как оно введет в заблуждение. Бесплатно на 14 дней, без кредитной карты.