Documentación en TypeScript: cómo escribir código que habla por sí mismo

Introducción: por qué la documentación no es una obligación aburrida, sino un superpoder

Imagine: vuelve a su proyecto después de seis meses. Abre el archivo con la lógica de autorización y ve un mar de código en TypeScript. Los tipos están, las interfaces están definidas, pero ¿qué hace esta función? ¿Por qué el parámetro se llama opts y qué campos tiene? ¿Le suena familiar?

La documentación en TypeScript no son solo "comentarios para cumplir". Es una herramienta que convierte su código en una historia comprensible. Una buena documentación ahorra horas de depuración, acelera la incorporación de nuevos desarrolladores y hace que su API sea amigable. En este artículo, analizaremos las mejores prácticas para documentar proyectos TypeScript: desde comentarios básicos de JSDoc hasta la generación avanzada de documentación con TypeDoc. ¡Allá vamos!

1. JSDoc y TSDoc: la base de su documentación

TypeScript heredó de JavaScript el popular formato JSDoc, y luego la comunidad desarrolló TSDoc: una sintaxis estandarizada para TypeScript. Si escribe una biblioteca o una API, TSDoc es su elección. Es más estricto, se integra mejor con los editores y los generadores de documentación.

Etiquetas básicas de TSDoc

Aquí tiene el mínimo que todo desarrollador debería conocer:

\n
• @param — descripción del parámetro de la función
\n
• @returns — lo que devuelve la función
\n
• @throws — qué excepciones puede lanzar
\n
• @example — ejemplo de uso
\n
• @deprecated — marca de código obsoleto
\n

/**\n * Calcula el descuento de un producto teniendo en cuenta un código promocional.\n * \n * @param price - Precio original del producto (debe ser mayor que 0)\n * @param discountPercent - Porcentaje de descuento (de 0 a 100)\n * @param promoCode - Código promocional que puede aumentar el descuento\n * @returns Precio final después de aplicar el descuento\n * @throws {Error} Si el precio o el porcentaje son incorrectos\n * \n * @example\n * // Ejemplo: 20% de descuento en un producto de 1000 rublos\n * const finalPrice = calculateDiscount(1000, 20, 'SUMMER');\n * console.log(finalPrice); // 800\n */\nfunction calculateDiscount(\n  price: number,\n  discountPercent: number,\n  promoCode?: string\n): number {\n  if (price <= 0 || discountPercent < 0 || discountPercent > 100) {\n    throw new Error('Parámetros incorrectos');\n  }\n  \n  let discount = discountPercent;\n  if (promoCode === 'SUMMER') {\n    discount += 10; // descuento adicional\n  }\n  \n  return price * (1 - discount / 100);\n}\n

Consejo: Describa siempre los casos límite. Si un parámetro puede ser undefined, indíquelo en la descripción. Los tipos de TypeScript están bien, pero el lenguaje humano añade contexto.

2. Documente tipos e interfaces

Una de las principales características de TypeScript es su potente sistema de tipos. Pero incluso el tipo más estricto no explicará el propósito de un campo. Documente las interfaces con el mismo cuidado que las funciones.

/**\n * Configuración para la conexión a una API externa del clima.\n */\ninterface WeatherApiConfig {\n  /** URL base de la API (por ejemplo, https://api.weather.com) */\n  baseUrl: string;\n  \n  /** Clave de autenticación obtenida del proveedor */\n  apiKey: string;\n  \n  /** \n   * Número de segundos de espera por la respuesta del servidor.\n   * Por defecto, 5 segundos.\n   */\n  timeout?: number;\n  \n  /**\n   * Versión de la API. Si no se especifica, se usa la última estable.\n   * @deprecated Use el campo `version` en la URL\n   */\n  apiVersion?: string;\n}\n

Observe: para timeout indicamos el valor por defecto directamente en el comentario. Esto evita que el desarrollador tenga que buscar en el código fuente o en las pruebas.

3. Generación de documentación: convirtiendo comentarios en un sitio web

Escribir comentarios es la mitad del trabajo. Hay que saber convertirlos en una documentación útil. Para TypeScript, la mejor herramienta es TypeDoc. Analiza sus comentarios TSDoc