JSDoc

JSDoc 是 JavaScript 文档的一部分，允许在代码中添加注释和结构。与 Java 的 JavaDoc 类似，JSDoc 不是一个单独的代码文档，它可以帮助您在现代 Visual Studio Code 中获得自动完成的开发经验和提示信息。

为什么使用 JSDoc？

Mejora la mantenibilidad：Facilita entender el código meses después

智能自动完成：IDE 的主要建议

自动文档：通用 HTML 文档和注释部分

提示验证：TypeScript 需要时验证提示的比例

兼容性：Funciona 与 JavaScript vanilla 和现代框架

基本语法

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

具体的 el valor de retorno:

/**
 * @returns {Promise} 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} nombres - Lista de nombres
 * @param {Object.} edades - Mapa de nombres a edades
 */
function procesarDatos(nombres, edades) {
    // Implementación
}

可空联盟和类型

/**
 * @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 Code 集成

项目配置

在项目中创建存档“jsconfig.json”：

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

文献生成

安装 JSDoc

npm install -g jsdoc

JSDoc 配置

创建“jsdoc.json”文件：

{
    "source": {
        "include": ["src"],
        "includePattern": ".js$",
        "excludePattern": "(node_modules/|docs)"
    },
    "plugins": ["plugins/markdown"],
    "templates": {
        "cleverLinks": true,
        "monospaceLinks": true
    },
    "opts": {
        "recurse": true,
        "destination": "./docs"
    }
}

HTML 文档生成

jsdoc -c jsdoc.json

实践能力卓越

一致：在项目中保持统一的文档格式

/**
 * ✅ Buena documentación
 * @param {string} nombre
 * @returns {boolean}
 */
function validar(nombre) {}

/**
 * ❌ Documentación inconsistente
 * @param nombre: string
 * @return boolean
 */
function validar(nombre) {}

次要文献：

/**
 * 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) {}

美国的情况如下：

/**
 * 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') {}

工具和插件

ESLint：配置有效文档的规则

DocumentThis：VS Code 通用 JSDoc 自动扩展

更好的文档：Plantilla mejorada para la documentacióngenerada

JSDoc 是 JavaScript 中最重要的参数和管理工具。通过 IDE 的辅助功能和文档生成工具，可以创建强大的代码库并轻松管理。

下一步推荐：

在实际项目中配置 JSDoc

公共职能记录

配置编辑器以自动完成

在 CI/CD 管道中实现文档自动生成

附加资源

JSDoc 官方文档

JSDoc 备忘单

TypeScript 和 JSDoc

CLIS.CC