1. ¿Qué es Dokka y por qué usarla?

Dokka es un motor moderno de generación de documentación para el lenguaje Kotlin, desarrollado por JetBrains. A diferencia del tradicional JavaDoc, Dokka comprende las particularidades de Kotlin: null-safety, funciones de extensión, propiedades, corrutinas, clases sealed y otras construcciones únicas del lenguaje. Si escribes una librería o API en Kotlin, Dokka te permite crear automáticamente una documentación legible y estructurada en formatos HTML, Markdown, Javadoc o incluso JSON para su posterior procesamiento.

¿Por qué es necesaria? En primer lugar, Dokka simplifica enormemente el mantenimiento de la documentación en proyectos grandes: basta con escribir comentarios KDoc (el equivalente a JavaDoc, pero con soporte para Markdown) en el código, y la herramienta generará un sitio web listo para usar. En segundo lugar, Dokka puede combinar la documentación de varios módulos de Gradle o Maven en un solo proyecto, algo fundamental para librerías multimódulo. En tercer lugar, admite personalización mediante plantillas y plugins, lo que permite adaptar la apariencia al estilo corporativo.

Dokka se utiliza activamente en la documentación oficial de Kotlin (kotlinlang.org), en librerías como Ktor, Exposed, Kotlinx.serialization y muchas otras. Es el estándar de facto para documentar proyectos Kotlin, y si quieres que tu librería tenga un aspecto profesional, Dokka es imprescindible.

2. Instalación

Dokka se distribuye como un plugin para los sistemas de compilación Gradle y Maven. No existe un comando pip o npm independiente, ya que es una herramienta para el ecosistema JVM. A continuación, se muestran las instrucciones precisas para Gradle (Kotlin DSL), que es la forma más popular.

Gradle (Kotlin DSL) — plugin para un solo módulo

Añade lo siguiente a tu archivo build.gradle.kts:

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

dependencies {
    // Tus dependencias
}

// Configuración básica (opcional)
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>

Después de la configuración, ejecuta el comando:

./gradlew dokkaHtml       # para HTML
./gradlew dokkaGfm        # para Markdown (GFM)
./gradlew dokkaJavadoc    # para estilo Javadoc

3. Inicio rápido — ejemplo mínimo funcional

Crea un archivo Kotlin simple con comentarios KDoc:

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

/**
 * Calculadora simple que demuestra el funcionamiento de Dokka.
 *
 * @author PythonLib Team
 * @since 1.0.0
 */
class Calculator {

    /**
     * Suma dos números.
     *
     * @param a primer sumando
     * @param b segundo sumando
     * @return suma de a y b
     */
    fun add(a: Int, b: Int): Int = a + b

    /**
     * Divide un número entre otro.
     *
     * @param a dividendo
     * @param b divisor (no puede ser cero)
     * @return resultado de la división
     * @throws IllegalArgumentException si b == 0
     */
    fun divide(a: Double, b: Double): Double {
        require(b != 0.0) { "El divisor no puede ser cero" }
        return a / b
    }
}

Ejecuta ./gradlew dokkaHtml. En la carpeta build/dokka encontrarás la documentación generada.