OpenCode para Documentación de Código: Generación Automática y Mantenimiento

La documentación es el primer sacrificio cuando hay presión de tiempo. OpenCode puede generar documentación automáticamente desde el código, mantenerla sincronizada y crear guías comprensibles para desarrolladores nuevos. El resultado: código bien documentado sin el esfuerzo manual tradicional.

Este tutorial asume que dominas el flujo Plan/Build y los workflows especializados. Aquí nos enfocamos en documentación.

Documentación de Código (JSDoc/TSDoc)

Generación de JSDoc

[Plan Mode]

Añade JSDoc a todas las funciones en @src/services/UserService.ts:

Para cada función, incluye:
- Descripción breve
- @param con descripción
- @return con descripción
- @throws si lanza excepciones
- @example si es compleja

Sigue el estándar JSDoc.

OpenCode generará:

typescriptCopiar
/**
 * Busca un usuario por su ID.
 * 
 * @param id - El ID del usuario a buscar
 * @returns El usuario encontrado o null si no existe
 * @throws {ValidationError} Si el ID es inválido
 * @throws {DatabaseError} Si hay un error de base de datos
 * 
 * @example
 * ```typescript
 * const user = await userService.findById('123');
 * if (user) {
 *   console.log(user.name);
 * }
 * ```
 */
async function findById(id: string): Promise<User | null> {
  // ...
}

Documentación de interfaces

Añade TSDoc a @src/types/User.ts:

Para cada propiedad, incluye:
- Descripción
- @example si es compleja
- @deprecated si está obsoleta
- @see si hay referencias relacionadas

typescriptCopiar
/**
 * Representa un usuario en el sistema.
 * 
 * @remarks
 * Los usuarios pueden tener múltiples roles y permisos.
 * 
 * @example
 * ```typescript
 * const user: User = {
 *   id: '123',
 *   name: 'John Doe',
 *   email: 'john@example.com',
 *   role: 'admin'
 * };
 * ```
 */
export interface User {
  /** Identificador único del usuario */
  id: string;
  
  /** Nombre completo del usuario */
  name: string;
  
  /** Email del usuario (debe ser único) */
  email: string;
  
  /** Rol del usuario en el sistema */
  role: UserRole;
}

Documentación de Componentes React

Props documentation

[Plan Mode]

Añade documentación a los props de @src/components/Button.tsx:

Usa el formato de comentarios de TypeScript para documentar:
- Cada prop
- Valores por defecto
- Si es opcional
- Ejemplos de uso

typescriptCopiar
interface ButtonProps {
  /**
   * El texto a mostrar en el botón.
   * @default 'Click me'
   */
  children?: React.ReactNode;
  
  /**
   * La variante visual del botón.
   * 
   * @remarks
   * - `primary`: Para acciones principales
   * - `secondary`: Para acciones secundarias
   * - `ghost`: Para acciones sutiles
   */
  variant?: 'primary' | 'secondary' | 'ghost';
  
  /**
   * Tamaño del botón.
   * @default 'md'
   */
  size?: 'sm' | 'md' | 'lg';
  
  /**
   * Si el botón está deshabilitado.
   * @default false
   */
  disabled?: boolean;
  
  /**
   * Callback cuando se hace click.
   */
  onClick?: () => void;
}

Stories para componentes

[Plan Mode]

Genera stories de Storybook para @src/components/Card.tsx:

Incluye:
- Variante por defecto
- Todas las variantes
- Estados (loading, error, empty)
- Ejemplos de uso real
- Controles interactivos

typescriptCopiar
// @src/components/Card.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Card } from './Card';

const meta: Meta<typeof Card> = {
  title: 'Components/Card',
  component: Card,
  tags: ['autodocs'],
};

export default meta;
type Story = StoryObj<typeof Card>;

export const Default: Story = {
  args: {
    title: 'Card Title',
    children: 'Card content goes here',
  },
};

export const WithActions: Story = {
  args: {
    title: 'Card with Actions',
    children: 'This card has action buttons',
    actions: [
      { label: 'Cancel', variant: 'ghost' },
      { label: 'Confirm', variant: 'primary' },
    ],
  },
};

export const Loading: Story = {
  args: {
    title: 'Loading Card',
    children: 'This card is in loading state',
    loading: true,
  },
};

Documentación de APIs

OpenAPI/Swagger

[Plan Mode]

Genera especificación OpenAPI para @src/api/users.ts:

Incluye:
- Todos los endpoints
- Parámetros con descripciones
- Request/response schemas
- Códigos de error
- Ejemplos de requests/responses
- Autenticación requerida

Formato: YAML o JSON

OpenCode generará:

yamlCopiar
openapi: 3.0.0
info:
  title: Users API
  version: 1.0.0
paths:
  /api/users:
    get:
      summary: List all users
      description: Returns a paginated list of users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'

Documentación de endpoints

Genera documentación en Markdown para cada endpoint:

Para @src/api/auth.ts, crea @docs/api/auth.md con:
- Descripción del endpoint
- Parámetros
- Request body schema
- Response schema
- Errores posibles
- Ejemplos de uso con curl
- Ejemplos en JavaScript

markdownCopiar
# Authentication API

## POST /api/auth/login

Authenticates a user with email and password.

### Request Body

```json
{
  "email": "user@example.com",
  "password": "securepassword"
}

Response

jsonCopiar
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "123",
    "name": "John Doe",
    "email": "user@example.com"
  }
}

Errors

• 400: Invalid credentials
• 429: Too many attempts (rate limited)
• 500: Server error

Example

bashCopiar
curl -X POST https://api.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"securepassword"}'

## READMEs y Guías

### README del proyecto

[Plan Mode]

Genera un README.md completo para el proyecto:

Incluye:

• Descripción del proyecto
• Stack tecnológico
• Instalación
• Scripts disponibles
• Estructura del proyecto
• Configuración de entorno
• Cómo contribuir
• Licencia

Usa el contenido de @AGENTS.md como referencia.

OpenCode generará:

```markdown
# Project Name

Description of what this project does.

## Tech Stack

- **Frontend**: Next.js 15, React 19, TypeScript
- **Backend**: Node.js, Express, Prisma
- **Database**: PostgreSQL
- **Testing**: Vitest, Playwright
- **Styling**: Tailwind CSS, shadcn/ui

## Installation

```bash
npm install

Development

bashCopiar
npm run dev

Available Scripts

Script	Description
npm run dev	Start development server
npm run build	Build for production
npm test	Run unit tests
npm run test:e2e	Run E2E tests
npm run lint	Run ESLint

Project Structure

src/
├── app/           # Next.js App Router
├── components/    # React components
├── lib/           # Utility functions
├── services/      # Business logic
└── types/         # TypeScript types

Environment Variables

See .env.example for required variables.

Contributing

See CONTRIBUTING.md for guidelines.

### Guías específicas

[Plan Mode]

Genera guías para desarrolladores nuevos:

1. @docs/setup.md - Cómo configurar el entorno local
2. @docs/architecture.md - Arquitectura del proyecto
3. @docs/workflow.md - Flujo de trabajo del equipo
4. @docs/deployment.md - Cómo desplegar

Usa @AGENTS.md como fuente de verdad.

## Documentación de Migraciones

### Changelogs

[Plan Mode]

Genera un CHANGELOG.md basado en los commits desde la última versión:

Analiza los commits y categoriza:

• Added
• Changed
• Deprecated
• Removed
• Fixed
• Security

Sigue el formato de Keep a Changelog.

```markdown
# Changelog

## [1.2.0] - 2026-06-21

### Added
- JWT authentication system
- User profile management
- Email notifications

### Changed
- Migrated from session-based to token-based auth
- Updated database schema for user roles

### Deprecated
- Old session endpoints (will be removed in v2.0)

### Fixed
- Fixed validation bug in user registration
- Fixed memory leak in data processing

### Security
- Added rate limiting to auth endpoints
- Updated dependencies for security patches

Guías de migración

[Plan Mode]

Genera guía de migración para cambios breaking:

Cambio: Migración de autenticación de sesiones a JWT

Incluye:
- Qué cambia
- Por qué cambia
- Cómo migrar código existente
- Pasos específicos
- Ejemplos antes/después
- Timeline de deprecación

Archivo: @docs/migrations/jwt-auth.md

Mantenimiento de Documentación

Sincronización con código

[Plan Mode]

Este código en @src/services/UserService.ts cambió:
- Se añadió el parámetro `options` a `findById`
- Se eliminó el método `deleteUser`

Actualiza la documentación en:
- @docs/api/users.md
- JSDoc en UserService.ts
- README si es relevante

Asegúrate que la documentación refleje el código actual.

Verificación de documentación

[Plan Mode]

Verifica que toda la documentación esté actualizada:

1. Compara JSDoc con implementación real
2. Verifica que todos los endpoints estén documentados
3. Verifica que los ejemplos de código funcionen
4. Busca documentación obsoleta
5. Busca código sin documentar

Genera un reporte de inconsistencias.

Workflows de Documentación

Workflow 1: Doc-as-you-code

1. Escribir código
2. [Plan Mode] Pedir JSDoc para funciones nuevas
3. [Build Mode] Aplicar JSDoc
4. Commitear código + documentación juntos

Workflow 2: Doc-after-feature

1. Completar feature
2. [Plan Mode] Pedir documentación completa:
   - JSDoc de funciones
   - Documentación de API
   - Actualización de README
   - Changelog entry
3. Revisar documentación generada
4. Commitear en commit separado

Workflow 3: Doc-sync

1. Antes de release, ejecutar verificación de docs
2. [Plan Mode] Pedir verificación de sincronización
3. Corregir inconsistencias
4. Actualizar changelog
5. Release

Errores Comunes en Documentación

Error	Causa	Solución
Documentación desactualizada	Código cambia, docs no	Usa workflow de doc-sync
Ejemplos que no funcionan	Código de ejemplo no probado	Ejecuta ejemplos antes de documentar
Documentación genérica	No entender contexto del código	Añade contexto específico del dominio
Demasiada documentación	Documentar todo indiscriminadamente	Documenta lo público y complejo
Falta de ejemplos	Solo descripciones teóricas	Añade ejemplos prácticos siempre

Herramientas de Documentación

TypeDoc para TypeScript

[Plan Mode]

Configura TypeDoc para generar documentación HTML desde
el código TypeScript:

- Instalar typedoc
- Configurar typedoc.json
- Añadir script npm run docs
- Configurar CI para generar docs en cada release

Genera la configuración completa.

jsonCopiar
{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "theme": "default",
  "excludePrivate": true,
  "excludeProtected": false,
  "includeVersion": true,
  "readme": "README.md"
}

Docusaurus para sitios de docs

[Plan Mode]

Genera sitio de documentación con Docusaurus:

- Configurar Docusaurus
- Migrar Markdown existente
- Añadir navegación
- Configurar búsqueda
- Integrar con CI/CD

Estructura: docs/ con contenido organizado.

Conclusión

Documentar con OpenCode requiere:

1. Generación inicial: Deja que OpenCode genere la base
2. Revisión humana: Verifica accuracy y claridad
3. Sincronización: Mantén docs actualizadas con código
4. Ejemplos prácticos: Siempre incluye código que funciona
5. Mantenimiento: Verifica periódicamente consistencia

En Binary Core, aumentamos la cobertura de documentación del 20% al 95% en 6 meses usando OpenCode. La clave no es documentar todo automáticamente, sino generar la base y luego mantenerla sincronizada con el código. La documentación es un activo vivo, no un estático.

¿Listo para migrar proyectos existentes? Aprende a usar OpenCode para migraciones de proyectos.

---

Serie completa:

1. Instalación y primeros pasos
2. Flujo de trabajo Plan/Build
3. Configuración avanzada
4. Debugging
5. Refactors
6. Generación de tests
7. Code review
8. Workflows especializados
9. Git workflows
10. Documentación (este artículo)