Documentación en JavaScript#
La documentación en JavaScript es crucial para asegurar que otros programadores puedan entender y utilizar eficazmente tu código. En este capítulo, exploraremos cómo documentar correctamente tus funciones y clases utilizando comentarios y JSDoc, una herramienta popular para generar documentación automática.
Comentarios en JavaScript#
Los comentarios en JavaScript son textos especiales que no afectan la ejecución del programa, pero son útiles para documentar el código y hacerlo más comprensible. Hay varios estilos de comentarios, pero los más relevantes para la documentación son los comentarios de bloque con /** ... */
, que son reconocidos por herramientas como JSDoc para generar documentación.
/**
* Esta función calcula la suma de dos números.
* @param {number} a - El primer número.
* @param {number} b - El segundo número.
* @returns {number} La suma de a y b.
*/
function sum(a, b) {
return a + b;
}
En este ejemplo:
@param
indica los parámetros que recibe la función y sus tipos.@returns
especifica el tipo de retorno de la función.
JSDoc#
JSDoc es una herramienta que convierte los comentarios especiales en código JavaScript en documentación legible automáticamente. Aquí están los pasos básicos para usar JSDoc:
Instalación de JSDoc:
Para instalar JSDoc globalmente, puedes ejecutar el siguiente comando:
sudo npm install -g jsdoc
Uso de JSDoc:
Puedes generar la documentación ejecutando el comando
jsdoc
seguido del nombre del archivo o directorio que contiene tus funciones y clases documentadas.Por ejemplo, para documentar un archivo
book.js
, puedes usar:jsdoc book.js
Estructura de los Comentarios JSDoc:
Los comentarios JSDoc tienen una estructura específica que incluye etiquetas especiales para describir los parámetros, retornos, constructores, propiedades, etc. A continuación, un ejemplo detallado:
/** * Representa un libro. * @constructor * @param {string} title - El título del libro. * @param {string} author - El autor del libro. */ function Book(title, author) { this.title = title; this.author = author; } /** * Obtiene el título del libro. * @returns {string} El título del libro. */ Book.prototype.getTitle = function() { return this.title; };
En este ejemplo:
@constructor
indica que la función es un constructor de una clase.@param
describe los parámetros que recibe el constructor.@returns
especifica el tipo de retorno de la función.
Integración con Visual Studio Code#
Visual Studio Code tiene soporte integrado para JSDoc, lo que significa que cuando comienzas a escribir /**
encima de una función o método, automáticamente te genera un esqueleto básico de comentarios JSDoc que puedes completar.