JSDoc: Panduan Definitif untuk Mendokumentasikan Kod JavaScript Anda

JSDoc ialah alat dokumentasi untuk JavaScript yang membolehkan anda menambah ulasan bertaip dan berstruktur pada kod anda. Sama seperti JavaDoc untuk Java, JSDoc bukan sahaja membantu mendokumenkan kod anda, tetapi juga meningkatkan pengalaman pembangunan dengan autolengkap dan menaip maklumat dalam editor moden seperti Visual Studio Code.

Mengapa menggunakan JSDoc?

• Meningkatkan kebolehselenggaraan: Menjadikan lebih mudah untuk memahami kod beberapa bulan kemudian
• Autolengkap pintar: IDE boleh memberikan cadangan yang lebih tepat
• Dokumentasi automatik: Hasilkan dokumentasi HTML daripada ulasan
• Pengesahan Jenis: Menyediakan semakan jenis tanpa memerlukan TypeScript
• Keserasian: Berfungsi dengan JavaScript vanila dan rangka kerja moden

Sintaks Asas

Struktur Komen JSDoc

Komen JSDoc bermula dengan /**dan berakhir dengan*/:

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

Tag Utama

@param

Dokumenkan parameter fungsi:

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

@kembali

Menentukan nilai pulangan:

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

@typedef

Tentukan jenis tersuai:

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

@panggil balik

Mentakrifkan jenis untuk fungsi panggil balik:

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

Jenis Kompleks

Tatasusunan dan Objek

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

Kesatuan dan Jenis Boleh Batal

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

Dokumentasi Kelas

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

Integrasi dengan Kod VS

Tetapan projek

Buat fail jsconfig.json dalam akar projek anda:

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

Penjanaan Dokumentasi

Memasang JSDoc

npm install -g jsdoc

Konfigurasi JSDoc

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

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

Amalan Terbaik

1. Tekal: Kekalkan gaya dokumentasi yang seragam sepanjang projek

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

1. Dokumenkan kesan sampingan:

/**
 * @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. Gunakan contoh untuk kes kompleks:

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

Alat dan Pemalam

1. ESLint: Konfigurasikan peraturan untuk mengesahkan dokumentasi
2. DocumentThis: Sambungan Kod VS untuk menjana JSDoc secara automatik
3. dokumen yang lebih baik: Templat yang dipertingkatkan untuk dokumentasi yang dijana

JSDoc ialah alat berkuasa yang meningkatkan kualiti dan kebolehselenggaraan kod JavaScript anda dengan ketara. Dengan sokongan IDE dan alatan penjanaan dokumentasi yang betul, anda boleh mencipta pangkalan kod yang lebih mantap dan boleh diselenggara.

Langkah seterusnya yang disyorkan:

1. Konfigurasikan JSDoc dalam projek semasa anda
2. Mulakan dengan mendokumentasikan fungsi awam
3. Sediakan editor anda untuk memanfaatkan autolengkap
4. Laksanakan penjanaan dokumentasi automatik dalam saluran paip CI/CD anda

Sumber Tambahan

• Dokumentasi Rasmi JSDoc
• JSDoc CheatSheet
• TypeScript dan JSDoc

Atas ialah kandungan terperinci JSDoc: Panduan Definitif untuk Mendokumentasikan Kod JavaScript Anda. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!