JSDoc: The Definitive Guide to Documenting Your JavaScript Code

JSDoc is a documentation tool for JavaScript that allows you to add typed and structured comments to your code. Similar to JavaDoc for Java, JSDoc not only helps document your code, but also improves the development experience with autocompletion and type information in modern editors like Visual Studio Code.

Why use JSDoc?

• Improves maintainability: Makes it easier to understand the code months later
• Smart autocomplete: IDEs can provide more accurate suggestions
• Automatic documentation: Generate HTML documentation from comments
• Type Validation: Provides type checking without the need for TypeScript
• Compatibility: Works with vanilla JavaScript and modern frameworks

Basic Syntax

Structure of a JSDoc Comment

JSDoc comments start with /**and end with*/:

/**
 * 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;
}

Main Tags

@param

Document the parameters of a function:

/**
 * @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

Specifies the return value:

/**
 * @returns {Promise<User>} Promesa que resuelve con los datos del usuario
 */
async function obtenerUsuario() {
    // Implementación
}

@typedef

Define custom types:

/**
 * @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

Defines types for callback functions:

/**
 * @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
    }
}

Complex Types

Arrays and Objects

/**
 * @param {Array<string>} nombres - Lista de nombres
 * @param {Object.<string, number>} edades - Mapa de nombres a edades
 */
function procesarDatos(nombres, edades) {
    // Implementación
}

Unions and Nullable Types

/**
 * @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
}

Class Documentation

/**
 * 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;
    }
}

Integration with VS Code

Project settings

Create a jsconfig.json file in the root of your project:

{
    "compilerOptions": {
        "checkJs": true,
        "strictNullChecks": true,
        "strictFunctionTypes": true
    },
    "exclude": ["node_modules", "dist"]
}

Documentation Generation

JSDoc installation

npm install -g jsdoc

JSDoc configuration

Create a jsdoc.json file:

/**
 * 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;
}

HTML documentation generation

/**
 * @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
}

Best Practices

1. Be consistent: Maintain a uniform documentation style throughout the project

/**
 * @returns {Promise<User>} Promesa que resuelve con los datos del usuario
 */
async function obtenerUsuario() {
    // Implementación
}

1. Document side effects:

/**
 * @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
}

1. Use examples for complex cases:

/**
 * @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
    }
}

Tools and Plugins

1. ESLint: Configure rules to validate documentation
2. DocumentThis: VS Code extension to generate JSDoc automatically
3. better-docs: Improved template for generated documentation

JSDoc is a powerful tool that significantly improves the quality and maintainability of your JavaScript code. With the right IDE support and documentation generation tools, you can create a more robust and maintainable codebase.

Recommended next steps:

1. Configure JSDoc in your current project
2. Start by documenting public functions
3. Set up your editor to take advantage of autocomplete
4. Implement automatic documentation generation in your CI/CD pipeline

Additional Resources

• Official JSDoc Documentation
• JSDoc CheatSheet
• TypeScript and JSDoc

The above is the detailed content of JSDoc: The Definitive Guide to Documenting Your JavaScript Code. For more information, please follow other related articles on the PHP Chinese website!