La documentación adecuada del código es un aspecto importante, aunque a menudo pasado por alto, del desarrollo de software. Como desarrollador, estará acostumbrado a escribir código limpio y eficiente, pero es posible que tenga menos experiencia en escribir buena documentación.
Una buena documentación es útil para cualquiera que trabaje con su código, ya sean otros miembros de su equipo o usted mismo en una fecha posterior. Puede explicar por qué ha implementado algo de una manera particular o cómo usar una función o API en particular.
Para los desarrolladores de JavaScript, JSDoc es una buena manera de comenzar a documentar su código.
Tabla de contenido
¿Qué es JSDoc?
Documentar el código puede ser complejo y tedioso. Sin embargo, cada vez más personas reconocen los beneficios de un enfoque de «documentos como código» y muchos lenguajes tienen bibliotecas que ayudan a automatizar el proceso. Para documentación simple, clara y concisa. Así como el lenguaje Go tiene GoDoc para automatizar la documentación a partir del código, JavaScript tiene JSDoc.
JSDoc genera documentación interpretando comentarios especiales en su código fuente JavaScript, procesando estos comentarios y produciendo documentación personalizada. Luego pone esta documentación a disposición en un formato HTML accesible.
Esto mantiene la documentación dentro del código, por lo que cuando actualiza su código, es fácil actualizar la documentación.
Configurando JSDoc
Los creadores de JSDoc han hecho que sea fácil comenzar y configurar JSDoc en su proyecto JavaScript.
Para instalar JSDoc localmente, ejecute:
npm install --save-dev jsdoc
Esto instalará la biblioteca en su proyecto como una dependencia de desarrollo.
Para usar JSDoc, utilizará comentarios de sintaxis especiales dentro de su código fuente. Escribirá todos los comentarios de su documentación dentro de los marcadores /** y */. Dentro de estos, puede describir variables definidas, funciones, parámetros de funciones y mucho más.
Por ejemplo:
* Gets User by name.
* @param {string} name - The name of the User
* @returns {string} User
*/function getUser(name) {
const User = name;
return User;
}
Las etiquetas @param y @returns son dos de las muchas palabras clave especiales que admite JSDoc para explicar su código.
Para generar la documentación para este código, ejecute npx jsdoc seguido de la ruta a su archivo JavaScript.
Por ejemplo:
npx jsdoc src/main.js
Si instaló JSDoc globalmente, puede omitir el indicador npx y ejecutar:
Este comando generará una carpeta de salida en la raíz de su proyecto. Dentro de la carpeta, encontrará archivos HTML que representan las páginas de su documentación.
Puede ver la documentación configurando un servidor web local para alojarla o simplemente abriendo el archivo out/index.html dentro de un navegador. A continuación se muestra un ejemplo de cómo se verá una página de documentación de forma predeterminada:
Configurar la salida JSDoc
Puede crear un archivo de configuración para cambiar el comportamiento predeterminado de JSDoc.
Para hacerlo, cree un archivo conf.js y exporte un módulo JavaScript dentro de este archivo.
Por ejemplo:
module.exports = {
source: {
includePattern: ".+\\\\.js(doc|x)?$",
excludePattern: ["node_modules"],
},
recurseDepth: 5,
sourceType: "module",
opts: {
template: "path/to/template",
destination: "./docs/",
recurse: true,
},
};
Dentro del archivo de configuración hay varios Configuración de JSDoc opciones. La opción de plantilla le permite utilizar una plantilla para personalizar la apariencia de la documentación. La comunidad de JSDoc proporciona muchos plantillas que puedes usar. El paquete también le permite crear sus propias plantillas personalizadas.
Para cambiar la ubicación de la documentación generada, establezca la opción de configuración de destino en un directorio. El ejemplo anterior especifica una carpeta de documentos en la raíz del proyecto.
Utilice este comando para ejecutar JSDoc con un archivo de configuración:
jsdoc -c /path/to/conf.js
Para que sea más fácil ejecutar este comando, agréguelo como una entrada de script dentro de su archivo package.json:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Ahora puede ejecutar el comando de script npm dentro de una terminal.
Un ejemplo de documentación generada con JSDoc
A continuación se muestra una biblioteca aritmética simple con métodos de suma y resta.
Este es un ejemplo de código JavaScript bien documentado:
* A library for performing basic arithmetic operations.
* @module arithmetic
*/
module.exports = {
* Adds two numbers.
* @param {number} a - The first number.
* @param {number} b - The second number.
* @return {number} The sum of the two numbers.
* @throws {TypeError} If any of the arguments is not a number.
*
* @example
* const arithmetic = require('arithmetic');
* const sum = arithmetic.add(5, 10);
* console.log(sum);
*/
add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}return a + b;
},
* Subtracts the second number from the first number.
* @param {number} a - The number to subtract from.
* @param {number} b - The number to subtract.
* @return {number} The result of the subtraction.
* @throws {TypeError} If any of the arguments is not a number.
*
* @example
* const arithmetic = require('arithmetic');
* const difference = arithmetic.subtract(10, 5);
* console.log(difference);
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}return a - b;
}
};
Los comentarios de JSDoc proporcionan una descripción clara y completa de la biblioteca y sus métodos, que incluyen:
- Una descripción de la biblioteca y su propósito.
- Los parámetros de cada método, incluido su tipo y una breve descripción.
- El valor y tipo que devuelve cada método.
- Los errores que puede arrojar cada método y las condiciones que lo provocan.
- Un ejemplo de cómo utilizar cada método.
Los comentarios también incluyen la etiqueta @module para indicar que este archivo es un módulo y la etiqueta @example para proporcionar un ejemplo de código para cada método.
Documentar el código del desarrollador de la manera correcta
Como puede ver, JSDoc es una herramienta muy útil para comenzar a documentar código JavaScript. Con su fácil integración, puede generar documentación rápida y detallada a medida que escribe su código. También puede mantener y actualizar la documentación directamente en su espacio de trabajo.
Sin embargo, por muy útil que sea la automatización de JSDoc, aún debes seguir ciertas pautas para poder crear documentación de calidad.
