Documentar proyectos de TypeScript y JavaScript

Para documentar proyectos en TypeScript y JavaScript de forma que se genere documentación automáticamente, puedes usar JSDoc junto con herramientas como TypeDoc o ESDoc. Estas herramientas leen los comentarios JSDoc y generan documentación en HTML, Markdown u otros formatos.

Aquí tienes una guía práctica:

---

1. Instala TypeDoc

Si estás trabajando con TypeScript, TypeDoc es la herramienta más recomendada. Instálala con:

npm install --save-dev typedoc

Para JavaScript puedes optar por herramientas como JSDoc o ESDoc.

---

2. Configura JSDoc en tu código

Usa comentarios JSDoc para documentar tus funciones, clases, variables y más.

Ejemplo básico para funciones:

/**
 * Suma dos números y devuelve el resultado.
 * 
 * @param {number} a - El primer número.
 * @param {number} b - El segundo número.
 * @returns {number} La suma de los dos números.
 */
export function suma(a: number, b: number): number {
  return a + b;
}

---

Documentación para clases:

/**
 * Clase que representa un coche.
 */
export class Coche {
  /**
   * Marca del coche.
   */
  public marca: string;

  /**
   * Modelo del coche.
   */
  public modelo: string;

  /**
   * Crea una instancia de un coche.
   * 
   * @param {string} marca - La marca del coche.
   * @param {string} modelo - El modelo del coche.
   */
  constructor(marca: string, modelo: string) {
    this.marca = marca;
    this.modelo = modelo;
  }

  /**
   * Devuelve una descripción del coche.
   * 
   * @returns {string} Descripción del coche.
   */
  getDescripcion(): string {
    return `Este coche es un ${this.marca} ${this.modelo}.`;
  }
}

---

Documentación para tipos y enums:

/**
 * Los posibles estados de un pedido.
 * 
 * @enum {string}
 */
export enum EstadoPedido {
  PENDIENTE = "pendiente",
  EN_PROGRESO = "en progreso",
  COMPLETADO = "completado",
}

---

Documentación para objetos complejos:

/**
 * Representa un usuario.
 * 
 * @typedef {Object} Usuario
 * @property {string} id - El ID del usuario.
 * @property {string} nombre - El nombre del usuario.
 * @property {number} edad - La edad del usuario.
 */

---

3. Configurar TypeDoc

Crea un archivo de configuración typedoc.json para ajustar la salida y las opciones:

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "includeVersion": true,
  "excludePrivate": true,
  "tsconfig": "tsconfig.json"
}

Ejecuta TypeDoc con:

npx typedoc

Esto generará la documentación en la carpeta docs.

---

4. Buenas prácticas para escribir documentación

• Sé claro y conciso: Describe qué hace una función o clase y sus parámetros.
• Usa etiquetas adecuadas: Algunas de las etiquetas más comunes son:
  • @param – Describe un parámetro.
  • @returns – Describe el valor de retorno.
  • @example – Proporciona un ejemplo de uso.
  • @deprecated – Marca algo como obsoleto.
  • @see – Añade referencias adicionales.
  • @throws – Indica errores lanzados por una función.

Ejemplo avanzado:

/**
 * Divide dos números.
 * 
 * @param {number} numerador - El numerador.
 * @param {number} denominador - El denominador (debe ser distinto de 0).
 * @returns {number} El resultado de la división.
 * @throws {Error} Si el denominador es 0.
 * @example
 * // División simple
 * divide(6, 2); // 3
 */
export function divide(numerador: number, denominador: number): number {
  if (denominador === 0) {
    throw new Error("El denominador no puede ser 0.");
  }
  return numerador / denominador;
}

---

5. Documentar JavaScript sin TypeScript

Aunque TypeScript ya ofrece tipos, en JavaScript puro puedes usar JSDoc con etiquetas explícitas para simular el tipado.

Ejemplo en JavaScript:

/**
 * Multiplica dos números.
 *
 * @param {number} a - El primer número.
 * @param {number} b - El segundo número.
 * @returns {number} El resultado de la multiplicación.
 */
function multiplicar(a, b) {
  return a * b;
}