1. Qu'est-ce que Dokka et pourquoi l'utiliser ?

Dokka est un moteur moderne de génération de documentation pour le langage Kotlin, développé par JetBrains. Contrairement au JavaDoc traditionnel, Dokka comprend les spécificités de Kotlin : null-sécurité, fonctions d'extension, propriétés, coroutines, classes sealed et autres constructions uniques du langage. Si vous écrivez une bibliothèque ou une API en Kotlin, Dokka vous permet de créer automatiquement une documentation lisible et structurée aux formats HTML, Markdown, Javadoc, ou même JSON pour un traitement ultérieur.

Pourquoi l'utiliser ? Premièrement, Dokka simplifie considérablement la maintenance de la documentation dans les grands projets : il suffit d'écrire des commentaires KDoc (équivalent du JavaDoc, mais avec le support du Markdown) dans le code, et l'outil génère un site prêt à l'emploi. Deuxièmement, Dokka peut fusionner la documentation de plusieurs modules Gradle ou Maven en un seul projet, ce qui est essentiel pour les bibliothèques multi-modules. Troisièmement, il prend en charge la personnalisation via des templates et des plugins, permettant d'adapter l'apparence à votre charte graphique.

Dokka est activement utilisé dans la documentation officielle de Kotlin (kotlinlang.org), ainsi que dans les bibliothèques Ktor, Exposed, Kotlinx.serialization et bien d'autres. C'est le standard de facto pour documenter les projets Kotlin. Si vous souhaitez que votre bibliothèque ait un aspect professionnel, Dokka est un outil incontournable.

2. Installation

Dokka est distribué sous forme de plugin pour les systèmes de build Gradle et Maven. Il n'existe pas de commande pip ou npm dédiée, car il s'agit d'un outil pour l'écosystème JVM. Voici les instructions précises pour Gradle (Kotlin DSL), la méthode la plus courante.

Gradle (Kotlin DSL) — plugin pour un seul module

Ajoutez dans build.gradle.kts :

plugins {
    id("org.jetbrains.dokka") version "1.9.20"
}

dependencies {
    // Vos dépendances
}

// Configuration de base (optionnelle)
tasks.withType<org.jetbrains.dokka.gradle.DokkaTask>() {
    outputDirectory.set(file("$buildDir/dokka"))
}

Gradle (Groovy DSL)

plugins {
    id "org.jetbrains.dokka" version "1.9.20"
}

Maven

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <version>1.9.20</version>
    <executions>
        <execution>
            <phase>pre-site</phase>
            <goals>
                <goal>dokka</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Après la configuration, exécutez la commande :

./gradlew dokkaHtml       # pour HTML
./gradlew dokkaGfm        # pour Markdown (GFM)
./gradlew dokkaJavadoc    # pour le style Javadoc

3. Démarrage rapide — exemple minimal fonctionnel

Créez un fichier Kotlin simple avec des commentaires KDoc :

// src/main/kotlin/com/example/Calculator.kt
package com.example

/**
 * Calculatrice simple pour illustrer le fonctionnement de Dokka.
 *
 * @author PythonLib Team
 * @since 1.0.0
 */
class Calculator {

    /**
     * Additionne deux nombres.
     *
     * @param a le premier terme
     * @param b le second terme
     * @return la somme de a et b
     */
    fun add(a: Int, b: Int): Int = a + b

    /**
     * Divise un nombre par un autre.
     *
     * @param a le dividende
     * @param b le diviseur (ne peut pas être zéro)
     * @return le résultat de la division
     * @throws IllegalArgumentException si b == 0
     */
    fun divide(a: Double, b: Double): Double {
        require(b != 0.0) { "Le diviseur ne peut pas être zéro" }
        return a / b
    }
}

Exécutez ./gradlew dokkaHtml. Dans le dossier build/dokka