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;
}
Deja un comentario