TypeDoc para TypeScript: guía completa con ejemplos

¿Qué es TypeDoc y para qué sirve?

\n\n

TypeDoc es un potente generador de documentación para proyectos en TypeScript. Crea automáticamente páginas HTML hermosas y estructuradas basadas en tus comentarios en el código, escritos en formato JSDoc. Si alguna vez has escrito código en TypeScript y has querido obtener rápidamente documentación similar a la documentación oficial de TypeScript o de bibliotecas populares, TypeDoc es exactamente lo que necesitas.

\n\n

¿Para qué sirve? En el desarrollo moderno, la documentación no es un lujo, sino una necesidad. TypeDoc resuelve varias tareas clave:

\n

\n
• Automatización: No necesitas escribir documentación manualmente. Basta con añadir comentarios a funciones, clases, interfaces y tipos, y TypeDoc generará un sitio listo.
\n
• Actualización: La documentación siempre coincide con el código, ya que se genera directamente a partir de él.
\n
• Navegación: TypeDoc crea una navegación cómoda por el proyecto: estructura de árbol, búsqueda, enlaces a tipos.
\n
• Soporte de TypeScript: Comprende tipos complejos de TypeScript: genéricos, tipos utilitarios, sobrecargas de funciones, módulos y espacios de nombres.
\n
• Extensibilidad: TypeDoc admite temas, plugins y personalización.
\n

\n\n

TypeDoc es ideal para:

\n

\n
• Bibliotecas y paquetes distribuidos a través de npm.
\n
• Proyectos internos donde se necesita familiarizar rápidamente a nuevos desarrolladores con el código.
\n
• Documentación de API para aplicaciones de servidor en TypeScript.
\n
• Proyectos educativos donde la claridad es importante.
\n

\n\n

Instalación de TypeDoc

\n\n

TypeDoc se instala a través de npm (Node Package Manager). Asegúrate de tener Node.js instalado (versión 14 o superior).

\n\n

La forma más sencilla es instalar TypeDoc de forma global:

\n

npm install -g typedoc

\n\n

Sin embargo, para proyectos se recomienda instalarlo como dependencia local de desarrollo:

\n

npm install --save-dev typedoc

\n\n

Después de la instalación, puedes verificar la versión:

\n

npx typedoc --version

\n\n

Si usas Yarn:

\n

yarn add -D typedoc

\n\n

Para pnpm:

\n

pnpm add -D typedoc

\n\n

Inicio rápido con ejemplo de código

\n\n

Vamos a crear un proyecto simple y generar documentación para él.

\n\n

Paso 1: Crea el proyecto

\n

mkdir my-typedoc-project\ncd my-typedoc-project\nnpm init -y

\n\n

Paso 2: Instala TypeDoc

\n

npm install --save-dev typedoc

\n\n

Paso 3: Crea un archivo de código src/index.ts

\n

/**\n * Módulo para trabajar con operaciones matemáticas.\n * @module MathUtils\n */\n\n/**\n * Suma dos números.\n * @param a - Primer número\n * @param b - Segundo número\n * @returns Suma de a y b\n * @example\n * ```typescript\n * const result = add(2, 3);\n * console.log(result); // 5\n * ```\n */\nexport function add(a: number, b: number): number {\n    return a + b;\n}\n\n/**\n * Resta el segundo número del primero.\n * @param a - Minuendo\n * @param b - Sustraendo\n * @returns Diferencia de a y b\n */\nexport function subtract(a: number, b: number): number {\n    return a - b;\n}\n\n/**\n * Interfaz para representar un punto en el espacio bidimensional.\n */\nexport interface Point {\n    /** Coordenada X */\n    x: number;\n    /** Coordenada Y */\n    y: number;\n}\n\n/**\n * Calcula la distancia entre dos puntos.\n * @param p1 - Primer punto\n * @param p2 - Segundo punto\n * @returns Distancia entre los puntos\n */\nexport function distance(p1: Point, p2: Point): number {\n    const dx = p2.x - p1.x;\n    const dy = p2.y - p1.y;\n    return Math.sqrt(dx * dx + dy * dy);\n}