JSDoc：记录 JavaScript 代码的权威指南

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

联合和可空类型

/**
 * @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中文网其他相关文章！