Cómo documentar código JavaScript usando JSDoc

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 un momento 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.

¿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 idiomas tienen bibliotecas que ayudan a automatizar el proceso. Para documentación simple, clara y concisa. Al igual que el

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ás todos los comentarios de tu documentación dentro /** y */ marcadores. 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
 */
functiongetUser(name) {
const User = name;
return User;
}

El @param y @devoluciones Las etiquetas 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

jsdoc path/to/file.js

Este comando generará un afuera carpeta en la raíz de su proyecto. Dentro de la carpeta, encontrará archivos HTML que representan las páginas de su documentación.

Puedes ver la documentación haciendo clic en configurar un servidor web local para alojarlo, 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 ello, cree un conf.js archivo y exportar 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. El plantilla La opción le permite utilizar una plantilla para personalizar la apariencia de la documentación. La comunidad de JSDoc ofrece 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 el destino opción de configuración a un directorio. El ejemplo anterior especifica una documentos carpeta 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 guiones entrada dentro de tu paquete.json archivo:

"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
 },

Tu puedes ahora ejecute el comando de secuencia de comandos npm dentro de una terminal.

Un ejemplo de documentación generada con JSDoc

A continuación se muestra una biblioteca aritmética simple con agregar y sustraer métodos.

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); // 15
 */
 add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('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); // 5
 */
 subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a - b;
 }
//... other methods ...
};

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 el @módulo etiqueta para indicar que este archivo es un módulo y el @ejemplo etiqueta 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.