Dokka para Kotlin: guia completo com exemplos práticos

Introdução ao Dokka: o que é e para que serve

Dokka é uma ferramenta poderosa para gerar documentação a partir do código-fonte em Kotlin. Desenvolvido pela JetBrains, o Dokka é a solução oficial para criar documentação de projetos Kotlin. Ele analisa seu código, extrai comentários KDoc (o equivalente ao JavaDoc para Kotlin) e gera documentação estruturada em diversos formatos: HTML, Markdown, Javadoc e outros.

Por que usar o Dokka?

• Automação: Você não precisa escrever documentação manualmente. O Dokka gera tudo com base no seu código e comentários.
• Atualização constante: A documentação sempre reflete o código, pois é gerada diretamente dele.
• Suporte a Kotlin Multiplatform: O Dokka funciona perfeitamente com projetos multiplataforma, unificando a documentação de diferentes módulos (common, jvm, js, native).
• Flexibilidade: Você pode personalizar a aparência, o formato de saída e incluir ou excluir partes específicas do código.
• Integração: Integra-se facilmente com sistemas de build como Gradle e Maven.

O Dokka é indispensável para desenvolvedores de bibliotecas, APIs e projetos grandes, onde uma documentação de qualidade é essencial para os usuários.

Instalação do Dokka

O Dokka não é instalado via pip ou npm, pois é uma ferramenta do ecossistema Kotlin/JVM. A principal forma de instalação é através do sistema de build Gradle (recomendado) ou Maven.

Instalação via Gradle (Kotlin DSL)

// build.gradle.kts
plugins {
    id("org.jetbrains.dokka") version "1.9.20" // Verifique a versão mais recente
}

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

Instalação via Gradle (Groovy DSL)

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

Instalação via 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>

Primeiros passos: executando o Dokka pela primeira vez

Após conectar o plugin, você precisa escrever alguns comentários KDoc no seu código e executar a tarefa do Gradle.

Passo 1: Escreva o código com comentários

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

/**
 * Calculadora simples que realiza operações aritméticas básicas.
 *
 * @author PythonLib Team
 * @since 1.0.0
 */
class Calculadora {

    /**
     * Soma dois números inteiros.
     *
     * @param a Primeiro número a ser somado.
     * @param b Segundo número a ser somado.
     * @return A soma de a e b.
     */
    fun somar(a: Int, b: Int): Int = a + b

    /**
     * Divide um número por outro.
     *
     * @param dividendo Número a ser dividido.
     * @param divisor Número que divide. Não pode ser zero.
     * @return O resultado da divisão.
     * @throws IllegalArgumentException se o divisor for zero.
     */
    fun dividir(dividendo: Double, divisor: Double): Double {
        if (divisor == 0.0) throw IllegalArgumentException("Divisor não pode ser zero")
        return dividendo / divisor
    }
}

Passo 2: Execute a geração

No terminal, execute o comando:

./gradlew dokkaHtml

Após a execução, a documentação será gerada na pasta build/dokka/html. Abra o arquivo index.html no seu navegador.

Principais métodos e funções do Dokka (API Gradle)

O Dokka oferece uma API rica para personalizar a geração de documentação. Aqui estão os principais métodos e configurações que você usará com mais frequência.

1. dokkaHtml — Geração de HTML