JSDoc は、型指定および構(gòu)造化されたコメントをコードに追加できる JavaScript のドキュメント ツールです。 Java の JavaDoc と同様に、JSDoc はコードの文書化に役立つだけでなく、Visual Studio Code などの最新のエディターでのオートコンプリートや型情報(bào)により開発エクスペリエンスを向上させます。

JSDoc を使用する理由

• 保守性の向上: 數(shù)か月後のコードの理解が容易になります
• スマート オートコンプリート: IDE はより正確な提案を提供できます
• 自動(dòng)ドキュメント: コメントから HTML ドキュメントを生成
• 型検証: TypeScript
を必要とせずに型チェックを提供します。
• 互換性: バニラ JavaScript と最新のフレームワークで動(dòng)作します

基本的な構(gòu)文

JSDoc コメントの構(gòu)造

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

関數(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

戻り値を指定します:

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

@折り返し電話

コールバック関數(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
    }
}

複合型

配列とオブジェクト

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

共用體と Null 許容型

/**
 * @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 コードとの統(tǒng)合

プロジェクト設(shè)定

プロジェクトのルートに jsconfig.json ファイルを作成します。

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

ドキュメントの生成

JSDocのインストール

npm install -g jsdoc

JSDoc の設(shè)定

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. 一貫性を保つ: プロジェクト全體で統(tǒ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. 複雑なケースには例を使用します:

/**
 * @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: ドキュメントを検証するためのルールを構(gòu)成します
2. DocumentThis: JSDoc を自動(dòng)的に生成する VS Code 拡張機(jī)能
3. better-docs: 生成されたドキュメントのテンプレートを改善しました

JSDoc は、JavaScript コードの品質(zhì)と保守性を大幅に向上させる強(qiáng)力なツールです。適切な IDE サポートとドキュメント生成ツールを使用すると、より堅(jiān)牢で保守しやすいコードベースを作成できます。

推奨される次のステップ:

1. 現(xiàn)在のプロジェクトで JSDoc を構(gòu)成します
2. パブリック関數(shù)を文書化することから始めます
3. オートコンプリートを利用できるようにエディタを設(shè)定します
4. CI/CD パイプラインに自動(dòng)ドキュメント生成を?qū)g裝します

追加のリソース

• 公式 JSDoc ドキュメント
• JSDoc チートシート
• TypeScript と JSDoc

以上がJSDoc: JavaScript コードを文書化するための決定版ガイドの詳細(xì)內(nèi)容です。詳細(xì)については、PHP 中國(guó)語(yǔ) Web サイトの他の関連記事を參照してください。