Agente de Revisión Principal

Agente Revisor de Documentación IA

Mantiene tu documentación sincronizada con tu código

La documentación desactualizada es peor que ninguna documentación — engaña activamente. El Revisor de Documentación detecta cuándo los cambios de código hacen que la documentación sea incorrecta.

Qué Detecta el Revisor de Documentación

Los bugs silenciosos — documentación que miente

Documentación Desactualizada

Documentación que describe comportamiento antiguo — el tipo más peligroso de documentación

README obsoletoEjemplos de API antiguosParámetros deprecados documentados

Documentación de API Faltante

Funciones públicas y endpoints sin documentación adecuada

Exportaciones sin documentarDescripciones de parámetros faltantesSin docs de tipo de retorno

Comentarios Engañosos

Comentarios que dicen una cosa mientras el código hace otra — peor que ningún comentario

TODOs obsoletosExplicaciones incorrectasComentarios copiados y pegados

Drift de OpenAPI/Swagger

Docs de API que no coinciden con los endpoints reales — causa #1 de fallos de integración

Schema de respuesta incorrectoEndpoints faltantesDocs de auth desactualizados

Sync de Docs de Componentes

Documentación de Storybook y componentes que no refleja cambios de props

Props faltantesDefaults incorrectosEjemplos desactualizados

Desajuste de Definiciones de Tipo

Tipos TypeDoc/JSDoc que mienten sobre interfaces y firmas reales

Opcional marcado como requiredGenerics incorrectosUnion types faltantes

Tipos de Documentación Cubiertos

Cada lugar donde la documentación y el código pueden desincronizarse

JSDoc / TSDoc

Documentación de funciones y métodos

Archivos README

Resúmenes de proyectos y paquetes

Comentarios en línea

Explicaciones de código y TODOs

Documentación de API

Descripciones y ejemplos de endpoints

Definiciones de tipos

Comentarios de interfaces y tipos

Entradas de Changelog

Precisión del historial de versiones

Métrica Única

Puntuación de Deuda de Documentación

Como la deuda técnica, la deuda de documentación se acumula silenciosamente. Damos a tu base de código una Puntuación de Salud de Documentación — un solo número que muestra cuánto se han desviado tus docs de la realidad.

Rastrea la frescura de la documentación a lo largo del tiempo
Identifica archivos que cambiaron sin actualizaciones de docs
Prioriza qué arreglar primero

Salud de Documentación

73/100

README.md

Última actualización hace 45 días, código cambió 12 veces

src/api/

3 endpoints sin documentar

CHANGELOG.md

Entradas faltantes para v2.3.0, v2.3.1

src/utils/

8 funciones exportadas sin JSDoc

Tendencia este mes-5 puntos
Consciente del Framework

Conocimiento Profundo de Frameworks

No solo verificaciones genéricas de docs — entendemos los patrones de documentación de tu framework

Next.js / React

  • Documentación de props de componentes
  • Ejemplos de uso de hooks
  • Descripciones de route handlers
  • Docs de middleware

NestJS / Express

  • Sync de decoradores Swagger
  • Documentación de DTOs
  • Docs de métodos de controller
  • Descripciones de módulos

FastAPI / Django

  • Docstrings de modelos Pydantic
  • Descripciones de endpoints
  • Schemas de respuesta
  • Docs de query params

GraphQL

  • Descripciones de schema
  • Documentación de resolvers
  • Definiciones de tipos
  • Docs de Mutation/Query
Sugerencia de IA

Para la función processPayment(amount, currency, options):

/**
 * Procesa una transacción de pago
 * @param amount - Monto en centavos (entero)
 * @param currency - Código de moneda ISO 4217
 * @param options - Opciones de procesamiento
 * @param options.idempotencyKey - Clave única
 * @param options.metadata - Pares clave-valor personalizados
 * @returns Promise<PaymentResult>
 * @throws PaymentError si rechazado
 */
Impulsado por IA

No Solo Detección — Generación

Cuando encontramos documentación faltante o desactualizada, no solo lo reportamos —generamos la corrección. La IA analiza tus firmas de funciones, tipos de retorno y patrones de uso para sugerir documentación precisa.

Auto-Generar JSDoc

Crea documentación desde firmas de funciones y tipos

Actualizar Docs Existentes

Actualiza documentación desactualizada para coincidir con el código actual

Detectando Desviación de Documentación

Ejemplos reales de documentación que necesitaba actualización

Documentación de Parámetros Desactualizada

Desactualizado
/**
 * 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 muestra la firma antigua con parámetro posicional

Actualizado
/**
 * 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
}

Actualizar para coincidir con el patrón actual de objeto de opciones

Comentario Engañoso

Desactualizado
// 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
}

El comentario describe lógica de reintentos que no existe

Actualizado
// 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
}

El comentario refleja el comportamiento real

Desviación del README

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

El README hace referencia a un script eliminado y configuración antigua de Redis

Actualizado
## Installation
```bash
npm install
```

## Environment Variables
- `DATABASE_URL` - PostgreSQL connection string
- `CACHE_TTL` - Cache duration in seconds (default: 3600)

La documentación refleja el proceso de configuración actual

Análisis Semántico

Cómo Funciona el Revisor de Documentación

El Revisor de Documentación no solo verifica si existe la documentación — verifica que coincida con lo que el código realmente hace. Cuando cambias la firma de una función, marca el JSDoc.

Coincidencia Semántica

Compara lo que dice la documentación vs lo que hace el código

Detección de Cambios

Detecta cuándo los cambios de código invalidan la documentación cercana

Sugerencias de Actualización

Proporciona texto específico para corregir la documentación

Pipeline de Análisis

1

Comparar Código y Docs

Verifica si la documentación coincide con la implementación real

2

Detectar Cambios

Identifica cuándo los cambios de código invalidan la documentación existente

3

Marcar Discrepancias

Reporta documentación que podría engañar a los desarrolladores

4

Sugerir Actualizaciones

Proporciona texto específico para actualizar la documentación

Por Qué Importa la Precisión de la Documentación

La mala documentación cuesta más que ninguna documentación

Depuración Más Rápida

La documentación precisa significa que los desarrolladores no pierden horas siguiendo pistas falsas

Mejor Incorporación

Los nuevos desarrolladores pueden confiar en lo que leen en lugar de adivinar

Confianza en la API

Los usuarios pueden confiar en la documentación de tu API sin prueba y error

Cada cambio de código es una oportunidad para que la documentación se desvíe.
El Revisor de Documentación lo detecta cada vez.

La Deuda de Documentación Está en Todas Partes

Estos problemas pasan desapercibidos todos los días — hasta ahora

65%

de archivos README están desactualizados en 6 meses

40%

de comentarios JSDoc no coinciden con firmas de funciones

3.2h

tiempo promedio perdido depurando por docs incorrectos

80%

de docs de API les falta al menos un campo requerido

Mantén la Documentación y el Código
Sincronizados

Deja que el Revisor de Documentación detecte la desviación antes de que engañe. Gratis durante 14 días, sin tarjeta de crédito requerida.

Validación JSDoc
Sincronización README
Precisión de comentarios