JSDoc es una herramienta de documentación para JavaScript que permite agregar comentarios tipados y estructurados a tu código. Similar a JavaDoc para Java, JSDoc no solo ayuda a documentar tu código, sino que también mejora la experiencia de desarrollo con autocompletado e información de tipos en editores modernos como Visual Studio Code.
¿Por qué usar JSDoc?
- Mejora la mantenibilidad: Facilita entender el código meses después
- Autocompletado inteligente: Los IDEs pueden proporcionar sugerencias más precisas
- Documentación automática: Genera documentación HTML a partir de comentarios
- Validación de tipos: Proporciona verificación de tipos sin necesidad de TypeScript
- Compatibilidad: Funciona con JavaScript vanilla y con frameworks modernos
Sintaxis Básica
Estructura de un Comentario JSDoc
Los comentarios JSDoc comienzan con /** y terminan con */:
/**
* Calcula el área de un rectángulo.
* @param {number} ancho - El ancho del rectángulo
* @param {number} alto - El alto del rectángulo
* @returns {number} El área del rectángulo
*/
function calcularArea(ancho, alto) {
return ancho * alto;
}
Tags Principales
@param
Documenta los parámetros de una función:
/**
* @param {string} nombre - Nombre del usuario
* @param {number} [edad] - Edad del usuario (opcional)
* @param {Object} opciones - Opciones de configuración
* @param {boolean} opciones.activo - Estado del usuario
* @param {string} opciones.rol - Rol del usuario
*/
function crearUsuario(nombre, edad, opciones) {
// Implementación
}
@returns
Especifica el valor de retorno:
/**
* @returns {Promise<User>} Promesa que resuelve con los datos del usuario
*/
async function obtenerUsuario() {
// Implementación
}
@typedef
Define tipos personalizados:
/**
* @typedef {Object} Usuario
* @property {string} id - ID único del usuario
* @property {string} nombre - Nombre completo
* @property {number} edad - Edad del usuario
* @property {string[]} roles - Lista de roles asignados
*/
/**
* @param {Usuario} usuario
* @returns {boolean}
*/
function validarUsuario(usuario) {
// Implementación
}
@callback
Define tipos para funciones callback:
/**
* @callback ValidatorCallback
* @param {string} valor - Valor a validar
* @returns {boolean} Resultado de la validación
*/
/**
* @param {string} dato
* @param {ValidatorCallback} validador
*/
function procesarDato(dato, validador) {
if (validador(dato)) {
// Procesar dato
}
}
Tipos Complejos
Arrays y Objetos
/**
* @param {Array<string>} nombres - Lista de nombres
* @param {Object.<string, number>} edades - Mapa de nombres a edades
*/
function procesarDatos(nombres, edades) {
// Implementación
}
Uniones y Tipos Nullable
/**
* @param {string|number} id - ID que puede ser string o número
* @param {?string} descripcion - Descripción opcional (puede ser null)
*/
function buscarElemento(id, descripcion) {
// Implementación
}
Documentación de Clases
/**
* Representa un vehículo genérico.
* @class
*/
class Vehiculo {
/**
* Crea una instancia de Vehiculo.
* @param {string} marca - Marca del vehículo
* @param {string} modelo - Modelo del vehículo
* @param {number} año - Año de fabricación
*/
constructor(marca, modelo, año) {
this.marca = marca;
this.modelo = modelo;
this.año = año;
}
/**
* Calcula la edad del vehículo.
* @returns {number} Edad en años
*/
obtenerEdad() {
return new Date().getFullYear() - this.año;
}
}
Integración con VS Code
Configuración del proyecto
Crea un archivo jsconfig.json en la raíz de tu proyecto:
{
"compilerOptions": {
"checkJs": true,
"strictNullChecks": true,
"strictFunctionTypes": true
},
"exclude": ["node_modules", "dist"]
}
Generación de Documentación
Instalación de JSDoc
npm install -g jsdoc
Configuración de JSDoc
Crea un archivo jsdoc.json:
{
"source": {
"include": ["src"],
"includePattern": ".js$",
"excludePattern": "(node_modules/|docs)"
},
"plugins": ["plugins/markdown"],
"templates": {
"cleverLinks": true,
"monospaceLinks": true
},
"opts": {
"recurse": true,
"destination": "./docs"
}
}
Generación de documentación HTML
jsdoc -c jsdoc.json
Mejores Prácticas
- Sé consistente: Mantén un estilo de documentación uniforme en todo el proyecto
/**
* ✅ Buena documentación
* @param {string} nombre
* @returns {boolean}
*/
function validar(nombre) {}
/**
* ❌ Documentación inconsistente
* @param nombre: string
* @return boolean
*/
function validar(nombre) {}
- Documenta los efectos secundarios:
/**
* Guarda el usuario en la base de datos.
* @param {Usuario} usuario
* @throws {Error} Si la conexión falla
* @fires {evento:usuarios:creado} Cuando el usuario es creado
*/
function guardarUsuario(usuario) {}
- Usa ejemplos para casos complejos:
/**
* Formatea una fecha según el locale especificado.
* @param {Date} fecha
* @param {string} [locale=es-ES]
* @returns {string}
* @example
* // Retorna "1 de enero de 2024"
* formatearFecha(new Date(2024, 0, 1), 'es-ES')
*/
function formatearFecha(fecha, locale = 'es-ES') {}
Herramientas y Plugins
- ESLint: Configura reglas para validar la documentación
- DocumentThis: Extension de VS Code para generar JSDoc automáticamente
- better-docs: Plantilla mejorada para la documentación generada
JSDoc es una herramienta poderosa que mejora significativamente la calidad y mantenibilidad de tu código JavaScript. Con el soporte adecuado del IDE y las herramientas de generación de documentación, puedes crear una base de código más robusta y fácil de mantener.
Próximos pasos recomendados:
- Configura JSDoc en tu proyecto actual
- Empieza documentando las funciones públicas
- Configura tu editor para aprovechar el autocompletado
- Implementa la generación automática de documentación en tu pipeline de CI/CD
Top comments (0)