Dokka Kotlin: métodos, ejemplos e instalación

Introducción a Dokka: qué es y para qué sirve

Dokka es una potente herramienta para generar documentación a partir del código fuente en Kotlin. Desarrollada por JetBrains, Dokka es la solución oficial para crear documentación de proyectos Kotlin. Analiza tu código, extrae los comentarios KDoc (el equivalente a JavaDoc para Kotlin) y genera documentación estructurada en varios formatos: HTML, Markdown, Javadoc y otros.

¿Por qué usar Dokka?

Automatización: No necesitas escribir documentación manualmente. Dokka la genera a partir de tu código y comentarios.
Actualización constante: La documentación siempre está sincronizada con el código, ya que se genera directamente desde él.
Soporte para Kotlin Multiplatform: Dokka funciona perfectamente con proyectos multiplataforma, unificando la documentación de diferentes módulos (common, jvm, js, native).
Flexibilidad: Puedes personalizar la apariencia, el formato de salida e incluir o excluir partes específicas del código.
Integración: Se integra fácilmente con sistemas de compilación como Gradle y Maven.

Dokka es indispensable para desarrolladores de librerías, APIs y proyectos grandes donde una documentación de calidad es fundamental para los usuarios.

Instalación de Dokka

Dokka no se instala mediante pip o npm, ya que es una herramienta del ecosistema Kotlin/JVM. La forma principal de instalación es a través del sistema de compilación Gradle (recomendado) o Maven.

Instalación con Gradle (Kotlin DSL)


// build.gradle.kts
plugins {
    id("org.jetbrains.dokka") version "1.9.20" // Verifica la versión más reciente
}

// O mediante apply plugin:
// apply(plugin = "org.jetbrains.dokka")

Instalación con Gradle (Groovy DSL)


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

Instalación con 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>

Primeros pasos: tu primera ejecución

Una vez conectado el plugin, solo necesitas escribir algunos comentarios KDoc en tu código y ejecutar la tarea de Gradle.

Paso 1: Escribe código con comentarios


// src/main/kotlin/com/ejemplo/Calculadora.kt

/**
 * Calculadora simple que realiza operaciones aritméticas básicas.
 *
 * @author PythonLib Team
 * @since 1.0.0
 */
class Calculadora {

    /**
     * Suma dos números enteros.
     *
     * @param a Primer sumando.
     * @param b Segundo sumando.
     * @return La suma de a y b.
     */
    fun sumar(a: Int, b: Int): Int = a + b

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