Dokka pour Kotlin : guide complet avec exemples

Introduction à Dokka : qu'est-ce que c'est et pourquoi l'utiliser ?

Dokka est un outil puissant pour générer de la documentation à partir du code source Kotlin. Développé par JetBrains, Dokka est la solution officielle pour créer la documentation des projets Kotlin. Il analyse votre code, extrait les commentaires KDoc (l'équivalent de JavaDoc pour Kotlin) et génère une documentation structurée dans plusieurs formats : HTML, Markdown, Javadoc, etc.

Pourquoi utiliser Dokka ?

• Automatisation : Fini la rédaction manuelle de la documentation. Dokka la génère automatiquement à partir de votre code et de vos commentaires.
• Mise à jour en continu : La documentation reste toujours synchronisée avec le code, puisqu'elle est générée directement à partir de celui-ci.
• Support Kotlin Multiplatform : Dokka fonctionne parfaitement avec les projets multiplateformes, en fusionnant la documentation des différents modules (common, jvm, js, native).
• Flexibilité : Personnalisez l'apparence, le format de sortie et incluez ou excluez des parties spécifiques de votre code.
• Intégration : S'intègre facilement avec les systèmes de build Gradle et Maven.

Dokka est indispensable pour les développeurs de bibliothèques, d'API et de grands projets où une documentation de qualité est cruciale pour les utilisateurs.

Installation de Dokka

Dokka ne s'installe pas via pip ou npm, car c'est un outil dédié à l'écosystème Kotlin/JVM. La méthode principale d'installation passe par le système de build Gradle (recommandé) ou Maven.

Installation avec Gradle (Kotlin DSL)

// build.gradle.kts
plugins {
    id("org.jetbrains.dokka") version "1.9.20" // Vérifiez la version la plus récente
}

// Ou via apply plugin :
// apply(plugin = "org.jetbrains.dokka")

Installation avec Gradle (Groovy DSL)

// build.gradle
plugins {
    id 'org.jetbrains.dokka' version '1.9.20'
}

Installation avec Maven

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

Premiers pas : votre première génération

Une fois le plugin ajouté, il vous suffit d'écrire quelques commentaires KDoc dans votre code et de lancer la tâche Gradle.

Étape 1 : Écrivez du code commenté

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

/**
 * Une calculatrice simple pour les opérations arithmétiques de base.
 *
 * @author PythonLib Team
 * @since 1.0.0
 */
class Calculator {

    /**
     * Additionne deux nombres entiers.
     *
     * @param a Le premier terme.
     * @param b Le deuxième terme.
     * @return La somme de a et b.
     */
    fun add(a: Int, b: Int): Int = a + b

    /**
     * Divise un nombre par un autre.
     *
     * @param dividend Le dividende.
     * @param divisor Le diviseur. Ne peut pas être zéro.
     * @return Le résultat de la division.
     * @throws IllegalArgumentException si le diviseur est zéro.
     */
    fun divide(dividend: Double, divisor: Double): Double {
        if (divisor == 0.0) throw IllegalArgumentException("Le diviseur ne peut pas être zéro")
        return dividend / divisor
    }
}

Étape 2 : Lancez la génération

Dans votre terminal, exécutez la commande :

./gradlew dokkaHtml

Une fois terminée, la documentation sera générée dans le dossier build/dokka/html. Ouvrez le fichier index.html dans votre navigateur.

Méthodes et fonctions principales de Dokka (API Gradle)

Dokka offre une API riche pour personnaliser la génération. Voici les méthodes et configurations les plus courantes que vous utiliserez.

1. dokkaHtml — Génération de documentation HTML