JSDoc: The Definitive Guide to Documenting Your JavaScript Code-JS Tutorial-php.cn

JSDoc: La Guía Definitiva para Documentar tu Código JavaScript

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

Copy after login

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
}

Copy after login

@returns

Specifies the return value:

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

Copy after login

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

Copy after login

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

Copy after login

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
}

Copy after login

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
}

Copy after login

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

Copy after login

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"]
}

Copy after login

Documentation Generation

JSDoc installation

npm install -g jsdoc

Copy after login

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

Copy after login

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
}

Copy after login

Best Practices

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
}

Copy after login

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
}

Copy after login

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
    }
}

Copy after login

Tools and Plugins

ESLint: Configure rules to validate documentation
DocumentThis: VS Code extension to generate JSDoc automatically
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:

Configure JSDoc in your current project
Start by documenting public functions
Set up your editor to take advantage of autocomplete
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!