1. O que é e para que serve

Dokka é um motor moderno de geração de documentação para a linguagem Kotlin, desenvolvido pela JetBrains. Diferente do JavaDoc tradicional, o Dokka entende as particularidades do Kotlin: null-safety, funções de extensão, propriedades, corrotinas, sealed classes e outras construções únicas da linguagem. Se você escreve uma biblioteca ou API em Kotlin, o Dokka permite criar automaticamente uma documentação legível e estruturada nos formatos HTML, Markdown, Javadoc ou até mesmo JSON para processamento posterior.

Para que serve? Primeiro, o Dokka simplifica muito a manutenção da documentação em projetos grandes — basta escrever comentários KDoc (similar ao JavaDoc, mas com suporte a Markdown) no código, e a ferramenta gera um site completo. Segundo, o Dokka consegue unificar a documentação de vários módulos Gradle ou Maven em um único projeto, essencial para bibliotecas multimódulo. Terceiro, ele oferece personalização através de templates e plugins, permitindo adaptar a aparência ao estilo corporativo.

O Dokka é amplamente utilizado na documentação oficial do Kotlin (kotlinlang.org), nas bibliotecas Ktor, Exposed, Kotlinx.serialization e muitas outras. É o padrão de facto para documentar projetos Kotlin. Se você quer que sua biblioteca tenha uma aparência profissional, o Dokka é indispensável.

2. Instalação

O Dokka é distribuído como um plugin para os sistemas de build Gradle e Maven. Não existe um comando pip ou npm separado, pois é uma ferramenta do ecossistema JVM. Abaixo estão as instruções exatas para Gradle (Kotlin DSL) — a forma mais popular.

Gradle (Kotlin DSL) — plugin para um único módulo

Adicione no build.gradle.kts:

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

dependencies {
    // Suas dependências
}

// Configuração 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>

Após a configuração, execute o comando:

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

3. Início rápido — exemplo mínimo funcional

Crie um arquivo Kotlin simples com comentários KDoc:

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

/**
 * Calculadora simples para demonstrar o funcionamento do Dokka.
 *
 * @author PythonLib Team
 * @since 1.0.0
 */
class Calculator {

    /**
     * Soma dois números.
     *
     * @param a primeira parcela
     * @param b segunda parcela
     * @return soma de a e b
     */
    fun add(a: Int, b: Int): Int = a + b

    /**
     * Divide um número por outro.
     *
     * @param a dividendo
     * @param b divisor (não pode ser zero)
     * @return resultado da divisão
     * @throws IllegalArgumentException se b == 0
     */
    fun divide(a: Double, b: Double): Double {
        require(b != 0.0) { "O divisor não pode ser zero" }
        return a / b
    }
}

Execute ./gradlew dokkaHtml. Na pasta build/dokka você encontrará a documentação gerada.