¿Qué es JSDoc?
JSDoc es una herramienta de documentación automática. Esta herramienta permite generar documentación a partir de los comentarios de nuestro código fuente, ahorrándonos el crear documentación al margen. Para ello, sólo tenemos que aprender a escribir una estructura especial que debemos utilizar en nuestros comentarios de código.
JSDoc no forma parte de Typescript, pero es una herramienta que es importante conocer antes de aprender Typescript. De esta forma, sabrás si en tu caso te interesa utilizar JSDoc, prefieres usar sólamente Typescript, o quieres utilizar ambos juntos. Son 3 alternativas totalmente factibles.
Ejemplo de código JSDoc
Antes de continuar, veamos un ejemplo de código para observar como tendríamos que escribir comentarios JSDoc. Los requisitos son los siguientes:
- Los comentarios siempre deben empezar por
/**y terminar por*/. - Los asteriscos de cada línea son opcionales, pero recomendados por legibilidad.
- Coloca sólo un espacio a continuación de los asteriscos.
/**
* Función que suma dos números.
* @param {number} a Primer número
* @param {number} b Segundo número
*
* @return {number} La suma de los dos números
*/
function sum(a,b) {
return a + b;
}
Observa que se trata de un comentario de cabecera con varias partes definidas:
- 1️⃣ Título: En la primera línea definimos lo que realiza la función.
- 2️⃣ Etiqueta: Prefijado por
@definimos de que se trata:@param,@return, ... - 3️⃣ Anotación de tipo: Entre llaves
{}definimos el tipo de dato:number,string, ... - 4️⃣ Parámetro: Nombre del parámetro. Usado en
@param. - 5️⃣ Descripción: Descripción de texto para explicar el objetivo o propósito.
- Ideal para información simple, que no requiere mucha explicación.
- Los comentarios siempre deben empezar por
/**y terminar por*/. - Sólo se puede indicar el título, no se pueden usar etiquetas como
@param,@return, etc.
/** Función que suma dos números. */
function sum(a,b) {
return a + b;
}
- 1️⃣ Título: Sólo definimos lo que realiza la función.
Ventajas de usar JSDoc
Además del objetivo principal explicado en el párrafo anterior, JSDoc nos proporciona varias ventajas considerables. Vamos a detallarlas todas:
- Estructura definida y legible para entender lo que hace nuestro código.
- Posibilidad de generar documentación a partir del código fuente.
- Autocompletado personalizado de nuestro código en editores como VSCode.
- Aunque se puede usar con Javascript, también es compatible con Typescript.
Simplemente con estos comentarios, el IDE o un editor como VSCode nos muestra un autocompletado personalizado de nuestro código, indicándonos las descripciones definidas en los comentarios:
Todas estas características hacen que nuestra experiencia al desarrollar sea mucho más cómoda, fácil e intuitiva. En los siguientes artículos veremos el formato a utilizar en otras características del lenguaje.
Ten en cuenta que estas características de JSDoc suelen venir integradas en el editor de texto que utilices. En nuestro caso, mostramos VSCode, uno de los editores con mejor soporte actualmente para desarrollo web.
Desventajas de JSDoc
Sin embargo, en algunos casos o para algunos programadores, utilizar JSDoc puede ser insuficiente (o incluso molesto) ya que tienes que añadir comentarios que pueden ser muy verbosos. Hay que tener muy en cuenta que los comentarios de JSDoc no son exactamente un reemplazo de Typescript, sino un añadido que se puede utilizar tanto con Javascript o con Typescript.
Lo recomendable es detectar primero cuál es nuestro caso de uso ideal:
| Caso de uso | Flexibilidad | Autocompletado | Documentación automática | Detección errores/tipos |
|---|---|---|---|---|
| Javascript sin JSDoc | ✅ | ❌ | ❌ | ❌ |
| Javascript con JSDoc | ✅ | ✅ | ✅ | ❌ |
| Typescript sin JSDoc | ❌ | ✅ | ❌ | ✅ |
| Typescript con JSDoc | ❌ | ✅ | ✅ | ✅ |
- Usar JSDoc+JS sólo permite documentar, anotar los tipos y ayuda de autocompletado, pero no realiza validaciones estrictas, ni te impide usar valores incorrectos.
- Los errores de tipo solo se detectan si usas una herramienta de análisis estático adicional, por lo que si esto es algo importante para ti, probablemente te interese más Typescript.
