JSDoc: Panduan Definitif untuk Mendokumentasikan Kod JavaScript Anda-tutorial js-php.cn

JSDoc: La Guía Definitiva para Documentar tu Código JavaScript

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

Salin selepas log masuk

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
}

Salin selepas log masuk

@kembali

Menentukan nilai pulangan:

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

Salin selepas log masuk

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

Salin selepas log masuk

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

Salin selepas log masuk

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
}

Salin selepas log masuk

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
}

Salin selepas log masuk

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

Salin selepas log masuk

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"]
}

Salin selepas log masuk

Penjanaan Dokumentasi

Memasang JSDoc

npm install -g jsdoc

Salin selepas log masuk

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

Salin selepas log masuk

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
}

Salin selepas log masuk

Amalan Terbaik

Tekal: Kekalkan gaya dokumentasi yang seragam sepanjang projek

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

Salin selepas log masuk

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
}

Salin selepas log masuk

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

Salin selepas log masuk

Alat dan Pemalam

ESLint: Konfigurasikan peraturan untuk mengesahkan dokumentasi
DocumentThis: Sambungan Kod VS untuk menjana JSDoc secara automatik
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:

Konfigurasikan JSDoc dalam projek semasa anda
Mulakan dengan mendokumentasikan fungsi awam
Sediakan editor anda untuk memanfaatkan autolengkap
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!