Escritura de documentación para proyectos TypeScript: de la A a la Z

Introducción: ¿por qué es necesaria la documentación en proyectos TypeScript?

La documentación de calidad no es solo un bono agradable, sino un elemento críticamente importante de cualquier proyecto profesional de TypeScript. Sirve como puente entre desarrolladores, facilita la incorporación de nuevos miembros al equipo y ayuda a evitar errores al usar la API. TypeScript, con su potente sistema de tipos, ofrece oportunidades únicas para generar documentación precisa y autodocumentada. En este artículo, analizaremos el proceso completo: desde escribir comentarios en el código hasta publicar la documentación terminada.

Fundamentos: JSDoc y anotaciones para TypeScript

TypeScript admite la sintaxis de JSDoc, lo que permite agregar comentarios estructurados directamente en el código. Esta es la base para crear documentación comprensible tanto para humanos como para herramientas.

Etiquetas básicas de JSDoc

Comencemos con un ejemplo simple de una función que suma dos números:

/**\n * Suma dos números.\n * @param a - Primer sumando.\n * @param b - Segundo sumando.\n * @returns La suma de dos números.\n */\nfunction add(a: number, b: number): number {\n    return a + b;\n}

Etiquetas clave:

\n
• @param — describe un argumento de función. Se recomienda indicar el tipo y el propósito.
\n
• @returns — describe el valor de retorno.
\n
• @throws — indica qué excepciones puede lanzar la función.
\n
• @example — muestra un ejemplo de uso.
\n

Documentación de tipos complejos

Para interfaces y tipos, use @property o describa los campos dentro del bloque:

interface UserConfig {\n    /** Nombre de usuario */\n    name: string;\n    /** Edad del usuario (opcional) */\n    age?: number;\n    /** Rol en el sistema */\n    role: 'admin' | 'user';\n}\n\n/**\n * Crea una configuración de usuario.\n * @param config - Objeto con la configuración del usuario.\n * @returns Objeto de configuración.\n */\nfunction createUser(config: UserConfig): UserConfig {\n    return config;\n}

Use @template para genéricos:

/**\n * Envoltura para almacenar un valor.\n * @template T - Tipo del valor almacenado.\n */\nclass Box<T> {\n    /** Valor almacenado */\n    value: T;\n    constructor(value: T) {\n        this.value = value;\n    }\n}

Herramientas para generar documentación: TypeDoc

TypeDoc es la herramienta principal para la generación automática de documentación a partir de anotaciones JSDoc en TypeScript. Crea un sitio HTML estático con navegación conveniente.

Instalación y configuración

Instale TypeDoc como dependencia de desarrollo:

npm install --save-dev typedoc

Cree un archivo de configuración typedoc.json en la raíz del proyecto:

{\n  "entryPoints": ["src/index.ts"],\n  "out": "docs",\n  "theme": "default",\n  "excludePrivate": true,\n  "excludeProtected": false,\n  "includeVersion": true,\n  "categorizeByGroup": true\n}

Parámetros de configuración:

\n
• entryPoints — punto de entrada a su proyecto (generalmente el archivo de exportación principal).
\n
• out — carpeta donde se generará la documentación.
\n
• excludePrivate — ocultar miembros privados de las clases.
\n
• includeVersion — agregar la versión del proyecto a la documentación.
\n

Ejecutar la generación

Agregue un script en package.json:

{\n  "scripts": {\n    "docs:generate": "typedoc"\n  }\n}

Ejecute el comando:

npm run docs:generate

Después de esto, aparecerá un sitio estático en la carpeta docs. Abra docs/index.html en su navegador.

Mejores prácticas para escribir documentación

Para que la documentación sea útil, siga algunas reglas.

1. Escriba comentar