Documentación automática con Deno

Uno de los principales beneficios de utilizar Typescript es que, mientras desarrollas tu código, también estás creando su documentación. Esto resulta invaluable al colaborar en equipos o al construir bibliotecas que otros desarrolladores utilizarán.

#Biblioteca Documentada

Supongamos que desarrollas una biblioteca para realizar operaciones aritméticas. Si planeas publicarla en registros como JSR o NPM, es esencial ofrecer documentación clara y detallada sobre cómo funciona y cómo debe ser usada.

Redactar documentación consume tiempo y, a menudo, como desarrolladores, no nos entusiasma hacerlo. Afortunadamente, Deno facilita la creación automática de documentación y puede generar un sitio web completo con un solo comando.

#Generando un Sitio Web de Documentación

Supongamos que has creado una función llamada multiply con tipos definidos explícitamente en TypeScript. Podemos aprovechar estos tipos para generar una documentación estructurada. Además, puedes agregar descripción detallada de la función mediante comentarios en formato TSDoc.

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

Utiliza el siguiente comando de Deno para generar documentación HTML:

deno doc --html <nombre-de-tu-libreria>.ts

Este comando generará un archivo index.html en tu proyecto. Puedes abrir este archivo en tu navegador para visualizar el sitio de documentación generado, que incluye toda la información a partir de los tipos y comentarios encontrados en tu código.

Generar documentación automática no solo reduce el tiempo dedicado a esta tarea, sino que también asegura que sea precisa y sincronizada con tu código. Es especialmente útil al compartir tu librería con terceros.

más posts