JSDoc? ??? ???? ???? ??? ??? ? ?? JavaScript? ?? ?????. Java? JavaDoc? ????? JSDoc? ??? ????? ? ??? ? ?? ??? Visual Studio Code? ?? ?? ???? ?? ?? ? ?? ??? ?? ?? ??? ?????.

? JSDoc? ??????

• ????? ??: ? ? ??? ??? ? ?? ??? ? ????
• ??? ?? ??: IDE? ?? ??? ??? ??? ? ????
• ?? ???: ???? HTML ?? ??
• ?? ??? ??: TypeScript ?? ?? ?? ?? ??
• ???: ??? JavaScript ? ?? ?????? ??

?? ??

JSDoc ??? ??

JSDoc ??? /**??? ?*/:
? ?????.

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

?? ??

@param

?? ???? ???:

/**
 * @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 {Promise<User>} Promesa que resuelve con los datos del usuario
 */
async function obtenerUsuario() {
    // Implementación
}

@typedef

??? ?? ?? ??:

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

?? ??

??? ??

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

??? ? Null ?? ??

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

?? ??

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

VS ??? ??

???? ??

???? ??? jsconfig.json ??? ?????.

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

?? ??

JSDoc ??

npm install -g jsdoc

JSDoc ??

jsdoc.json ?? ???:

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

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

?? ??

1. ???: ???? ??? ?? ??? ?? ???? ?????.

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

1. ?? ???:

/**
 * @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. ??? ???? ?? ?????:

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

?? ? ????

1. ESLint: ?? ??? ?? ?? ??
2. DocumentThis: JSDoc? ???? ???? VS Code ??
3. better-docs: ??? ??? ?? ??? ???

JSDoc? JavaScript ??? ??? ?? ???? ?? ????? ??? ?????. ??? IDE ?? ? ?? ?? ??? ???? ?? ???? ?? ??? ??? ?????? ?? ? ????.

???? ?? ??:

1. ?? ?????? JSDoc ??
2. ?? ??? ????? ??? ?????
3. ?? ?? ??? ????? ??? ??
4. CI/CD ?????? ?? ?? ?? ??

?? ???

• ?? JSDoc ??
• JSDoc ????
• TypeScript? JSDoc

? ??? JSDoc: JavaScript ?? ???? ?? ??? ???? ?? ?????. ??? ??? PHP ??? ????? ?? ?? ??? ?????!