Agente de Revisão Principal

Agente Revisor de Documentação IA

Mantém sua documentação sincronizada com seu código

Documentação desatualizada é pior que nenhuma documentação — ela engana ativamente. O Revisor de Documentação detecta quando mudanças no código tornam a documentação incorreta.

O Que o Revisor de Documentação Detecta

Os bugs silenciosos — documentação que mente

Documentação Desatualizada

Documentação que descreve comportamento antigo — o tipo mais perigoso de documentação

README obsoletoExemplos de API antigosParâmetros depreciados documentados

Documentação de API Ausente

Funções públicas e endpoints sem documentação adequada

Exportações não documentadasDescrições de parâmetros ausentesSem docs de tipos de retorno

Comentários Enganosos

Comentários que dizem uma coisa enquanto o código faz outra — pior que nenhum comentário

TODOs obsoletosExplicações incorretasComentários copiados e colados

Drift de OpenAPI/Swagger

Docs de API que não correspondem aos endpoints reais — causa #1 de falhas de integração

Schema de resposta incorretoEndpoints ausentesDocs de auth desatualizados

Sync de Docs de Componentes

Documentação de Storybook e componentes que não reflete mudanças de props

Props ausentesDefaults incorretosExemplos desatualizados

Desalinhamento de Definições de Tipo

Tipos TypeDoc/JSDoc que mentem sobre interfaces e assinaturas reais

Opcional marcado como requiredGenerics incorretosUnion types ausentes

Tipos de Documentação Cobertos

Cada lugar onde docs e código podem ficar dessincronizados

JSDoc / TSDoc

Documentação de funções e métodos

Arquivos README

Visão geral de projetos e pacotes

Comentários inline

Explicações de código e TODOs

Documentação de API

Descrições e exemplos de endpoints

Definições de tipos

Comentários de interfaces e tipos

Entradas de Changelog

Precisão do histórico de versões

Métrica Única

Pontuação de Dívida de Documentação

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.

Rastreie a atualização da documentação ao longo do tempo
Identifique arquivos que mudaram sem atualizações de docs
Priorize o que corrigir primeiro

Saúde da Documentação

73/100

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

Tendência este mês-5 pontos
Consciente do Framework

Conhecimento Profundo de Frameworks

Não apenas verificações genéricas de docs — entendemos os padrões de documentação do seu framework

Next.js / React

  • Documentação de props de componentes
  • Exemplos de uso de hooks
  • Descrições de route handlers
  • Docs de middleware

NestJS / Express

  • Sync de decoradores Swagger
  • Documentação de DTOs
  • Docs de métodos de controller
  • Descrições de módulos

FastAPI / Django

  • Docstrings de modelos Pydantic
  • Descrições de endpoints
  • Schemas de resposta
  • Docs de query params

GraphQL

  • Descrições de schema
  • Documentação de resolvers
  • Definições de tipos
  • Docs de Mutation/Query
Sugestão de IA

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
 */
Impulsionado por IA

Não Apenas Detecção — Geração

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.

Auto-Gerar JSDoc

Cria documentação a partir de assinaturas de funções e tipos

Atualizar Docs Existentes

Atualiza documentação desatualizada para corresponder ao código atual

Detectando Desvio de Documentação

Exemplos reais de documentação que precisava de atualização

Documentação de Parâmetros Desatualizada

Desatualizado
/**
 * 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

Atualizado
/**
 * 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

Comentário Enganoso

Desatualizado
// 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

Atualizado
// 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

Desvio do README

Desatualizado
## 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

Atualizado
## 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

Análise Semântica

Como o Revisor de Documentação Funciona

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.

Correspondência Semântica

Compara o que as docs dizem vs o que o código faz

Detecção de Mudanças

Percebe quando mudanças no código invalidam docs próximas

Sugestões de Atualização

Fornece texto específico para corrigir a documentação

Pipeline de Análise

1

Comparar Código e Docs

Verifica se a documentação corresponde à implementação real

2

Detectar Mudanças

Identifica quando mudanças no código invalidam a documentação existente

3

Marcar Discrepâncias

Reporta documentação que pode enganar desenvolvedores

4

Sugerir Atualizações

Fornece texto específico para atualizar a documentação

Por Que a Precisão da Documentação Importa

Documentação ruim custa mais que nenhuma documentação

Debugging Mais Rápido

Documentação precisa significa que desenvolvedores não perdem horas seguindo pistas falsas

Melhor Onboarding

Novos desenvolvedores podem confiar no que leem em vez de adivinhar

Confiança na API

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.

Dívida de Documentação Está em Todo Lugar

Esses problemas passam despercebidos todos os dias — até agora

65%

dos arquivos README ficam desatualizados em 6 meses

40%

dos comentários JSDoc não correspondem às assinaturas de função

3.2h

tempo médio perdido debugando devido a docs incorretas

80%

das docs de API faltam pelo menos um campo obrigatório

Mantenha Documentação e Código
Sincronizados

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.

Validação JSDoc
Sincronização README
Precisão de Comentários