JSDoc : le guide définitif pour documenter votre code JavaScript

JSDoc est un outil de documentation pour JavaScript qui vous permet d'ajouter des commentaires tapés et structurés à votre code. Semblable à JavaDoc pour Java, JSDoc aide non seulement à documenter votre code, mais améliore également l'expérience de développement grâce à la saisie semi-automatique et à la saisie d'informations dans des éditeurs modernes comme Visual Studio Code.

Pourquoi utiliser JSDoc ?

• Améliore la maintenabilité : facilite la compréhension du code des mois plus tard
• Complétion automatique intelligente : les IDE peuvent fournir des suggestions plus précises
• Documentation automatique : Générer une documentation HTML à partir des commentaires
• Validation de type : fournit une vérification de type sans avoir besoin de TypeScript
• Compatibilité : Fonctionne avec JavaScript Vanilla et les frameworks modernes

Syntaxe de base

Structure d'un commentaire JSDoc

Les commentaires JSDoc commencent par /**et terminer par*/:

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

Balises principales

@param

Documenter les paramètres d'une fonction :

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

@retours

Spécifie la valeur de retour :

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

@typedef

Définir des types personnalisés :

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

@rappel

Définit les types pour les fonctions de rappel :

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

Types complexes

Tableaux et objets

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

Unions et types nullables

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

Documentation de classe

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

Intégration avec VS Code

Paramètres du projet

Créez un fichier jsconfig.json à la racine de votre projet :

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

Génération de documentation

Installation de JSDoc

npm install -g jsdoc

Configuration JSDoc

Créez un fichier 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;
}

Génération de documentation 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
}

Meilleures pratiques

1. Soyez cohérent : Maintenez un style de documentation uniforme tout au long du projet

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

1. Documenter les effets secondaires :

/**
 * @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. Utiliser des exemples pour les cas complexes :

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

Outils et plugins

1. ESLint : Configurer les règles pour valider la documentation
2. DocumentThis : Extension VS Code pour générer automatiquement du JSDoc
3. better-docs : Modèle amélioré pour la documentation générée

JSDoc est un outil puissant qui améliore considérablement la qualité et la maintenabilité de votre code JavaScript. Avec le bon support IDE et les bons outils de génération de documentation, vous pouvez créer une base de code plus robuste et plus maintenable.

Prochaines étapes recommandées :

1. Configurez JSDoc dans votre projet actuel
2. Commencez par documenter les fonctions publiques
3. Configurez votre éditeur pour profiter de la saisie semi-automatique
4. Implémentez la génération automatique de documentation dans votre pipeline CI/CD

Ressources supplémentaires

• Documentation officielle JSDoc
• Aide-mémoire JSDoc
• TypeScript et JSDoc

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!