Os bugs silenciosos — documentação que mente
Documentação que descreve comportamento antigo — o tipo mais perigoso de documentação
Funções públicas e endpoints sem documentação adequada
Comentários que dizem uma coisa enquanto o código faz outra — pior que nenhum comentário
Docs de API que não correspondem aos endpoints reais — causa #1 de falhas de integração
Documentação de Storybook e componentes que não reflete mudanças de props
Tipos TypeDoc/JSDoc que mentem sobre interfaces e assinaturas reais
Cada lugar onde docs e código podem ficar dessincronizados
Documentação de funções e métodos
Visão geral de projetos e pacotes
Explicações de código e TODOs
Descrições e exemplos de endpoints
Comentários de interfaces e tipos
Precisão do histórico de versões
Como a dívida técnica, a dívida de documentação se acumula silenciosamente. Damos à sua base de código uma Pontuação de Saúde de Documentação — um único número que mostra o quanto suas docs desviaram da realidade.
README.md
Última atualização há 45 dias, código alterado 12 vezes
src/api/
3 endpoints não documentados
CHANGELOG.md
Entradas ausentes para v2.3.0, v2.3.1
src/utils/
8 funções exportadas sem JSDoc
Não apenas verificações genéricas de docs — entendemos os padrões de documentação do seu framework
Para a função processPayment(amount, currency, options):
/**
* Processa uma transação de pagamento
* @param amount - Valor em centavos (inteiro)
* @param currency - Código de moeda ISO 4217
* @param options - Opções de processamento
* @param options.idempotencyKey - Chave única
* @param options.metadata - Pares chave-valor personalizados
* @returns Promise<PaymentResult>
* @throws PaymentError se recusado
*/Quando encontramos documentação ausente ou desatualizada, não apenas reportamos —geramos a correção. A IA analisa suas assinaturas de funções, tipos de retorno e padrões de uso para sugerir documentação precisa.
Cria documentação a partir de assinaturas de funções e tipos
Atualiza documentação desatualizada para corresponder ao código atual
Exemplos reais de documentação que precisava de atualização
/**
* Fetches user by ID
* @param id - User ID
* @param includeDeleted - Include soft-deleted users
*/
async function getUser(id: string, options?: GetUserOptions) {
// includeDeleted moved to options object 3 months ago
// but JSDoc still shows old signature
}JSDoc mostra a assinatura antiga com parâmetro posicional
/**
* Fetches user by ID
* @param id - User ID
* @param options - Query options
* @param options.includeDeleted - Include soft-deleted users
* @param options.fields - Fields to select
*/
async function getUser(id: string, options?: GetUserOptions) {
// Documentation matches actual signature
}Atualizar para corresponder ao padrão atual de objeto de opções
// Retry 3 times with exponential backoff
async function fetchWithRetry(url: string) {
const MAX_RETRIES = 5 // Changed from 3
const response = await fetch(url)
// Actually no retry logic implemented anymore
return response
}O comentário descreve lógica de retry que não existe
// Simple fetch wrapper, no retry logic
// For retries, use fetchWithRetry from @/lib/http
async function simpleFetch(url: string) {
const response = await fetch(url)
return response
}O comentário reflete o comportamento real
## Installation
```bash
npm install
npm run setup # This script was removed
```
## Environment Variables
- `DATABASE_URL` - PostgreSQL connection
- `REDIS_URL` - Redis connection # We switched to in-memory cache
O README referencia um script removido e configuração antiga de Redis
## Installation
```bash
npm install
```
## Environment Variables
- `DATABASE_URL` - PostgreSQL connection string
- `CACHE_TTL` - Cache duration in seconds (default: 3600)
A documentação reflete o processo de configuração atual
O Revisor de Documentação não apenas verifica se a documentação existe — ele verifica se corresponde ao que o código realmente faz. Quando você muda uma assinatura de função, ele marca o JSDoc.
Compara o que as docs dizem vs o que o código faz
Percebe quando mudanças no código invalidam docs próximas
Fornece texto específico para corrigir a documentação
Comparar Código e Docs
Verifica se a documentação corresponde à implementação real
Detectar Mudanças
Identifica quando mudanças no código invalidam a documentação existente
Marcar Discrepâncias
Reporta documentação que pode enganar desenvolvedores
Sugerir Atualizações
Fornece texto específico para atualizar a documentação
Documentação ruim custa mais que nenhuma documentação
Documentação precisa significa que desenvolvedores não perdem horas seguindo pistas falsas
Novos desenvolvedores podem confiar no que leem em vez de adivinhar
Usuários podem confiar na documentação da sua API sem tentativa e erro
Cada mudança de código é uma oportunidade para as docs desviarem.
O Revisor de Documentação detecta toda vez.
Esses problemas passam despercebidos todos os dias — até agora
dos arquivos README ficam desatualizados em 6 meses
dos comentários JSDoc não correspondem às assinaturas de função
tempo médio perdido debugando devido a docs incorretas
das docs de API faltam pelo menos um campo obrigatório
Deixe o Revisor de Documentação detectar o desvio antes que engane. Grátis por 14 dias, sem cartão de crédito necessário.