JSDoc 是一個 JavaScript 文檔工具，允許您向代碼添加類型化和結(jié)構(gòu)化注釋。與 Java 的 JavaDoc 類似，JSDoc 不僅可以幫助記錄代碼，還可以通過 Visual Studio Code 等現(xiàn)代編輯器中的自動完成和類型信息來改善開發(fā)體驗(yàn)。

為什么使用 JSDoc？

• 提高可維護(hù)性：讓幾個月后更容易理解代碼
• 智能自動完成：IDE可以提供更準(zhǔn)確的建議
• 自動文檔：從注釋生成 HTML 文檔
• 類型驗(yàn)證：提供類型檢查，無需 TypeScript
• 兼容性：適用于普通 JavaScript 和現(xiàn)代框架

基本語法

JSDoc 注釋的結(jié)構(gòu)

JSDoc 注釋以 /**并結(jié)束于*/:
開頭

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

主要標(biāo)簽

@參數(shù)

記錄函數(shù)的參數(shù)：

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

@打回來

定義回調(diào)函數(shù)的類型：

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

復(fù)雜類型

數(shù)組和對象

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

聯(liá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 代碼集成

項(xiàng)目設(shè)置

在項(xiàng)目的根目錄中創(chuàng)建一個 jsconfig.json 文件：

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

文檔生成

JSDoc安裝

npm install -g jsdoc

JSDoc配置

創(chuàng)建 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
}

最佳實(shí)踐

1. 保持一致：在整個項(xiàng)目中保持統(tǒng)一的文檔風(fēng)格

/**
 * @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. 復(fù)雜情況的使用示例：

/**
 * @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：配置規(guī)則以驗(yàn)證文檔
2. DocumentThis：自動生成 JSDoc 的 VS Code 擴(kuò)展
3. better-docs：改進(jìn)的生成文檔模板

JSDoc 是一個強(qiáng)大的工具，可以顯著提高 JavaScript 代碼的質(zhì)量和可維護(hù)性。借助正確的 IDE 支持和文檔生成工具，您可以創(chuàng)建更強(qiáng)大且可維護(hù)的代碼庫。

建議的后續(xù)步驟：

1. 在當(dāng)前項(xiàng)目中配置 JSDoc
2. 從記錄公共函數(shù)開始
3. 設(shè)置編輯器以利用自動完成功能
4. 在 CI/CD 管道中實(shí)現(xiàn)自動文檔生成

其他資源

• JSDoc 官方文檔
• JSDoc 備忘單
• TypeScript 和 JSDoc

以上是JSDoc：記錄 JavaScript 代碼的權(quán)威指南的詳細(xì)內(nèi)容。更多信息請關(guān)注PHP中文網(wǎng)其他相關(guān)文章！