Escrevendo documentação para projetos Kotlin: do A ao Z

Introdução: por que a documentação é importante para projetos Kotlin

Escrever documentação não é apenas uma formalidade, mas um elemento-chave para o sucesso de um projeto Kotlin. Código bem documentado acelera a integração de novos desenvolvedores, simplifica a manutenção e reduz o número de erros. Kotlin, sendo uma linguagem moderna, oferece ferramentas poderosas para criar documentação: KDoc (análogo ao JavaDoc) e Dokka (gerador de documentação). Neste artigo, abordaremos o ciclo completo de escrita de documentação para um projeto Kotlin: desde comentários no código até a publicação da documentação pronta.

Independentemente de você estar trabalhando em uma biblioteca, API ou aplicação interna, seguir as melhores práticas de documentação tornará seu código compreensível e acessível. Vamos começar com o básico.

Fundamentos do KDoc: sintaxe e estrutura

KDoc é uma linguagem de marcação para documentar código Kotlin. Ela é baseada no JavaDoc, mas adaptada às particularidades do Kotlin: segurança contra nulos, funções de extensão, propriedades e lambdas. Os comentários KDoc começam com /** e terminam com */.

Estrutura básica de um comentário KDoc

Cada comentário KDoc consiste em uma descrição e tags opcionais. As principais tags são:

\n
• @param — descrição de um parâmetro de função
\n
• @return — descrição do valor de retorno
\n
• @throws ou @exception — descrição de uma exceção
\n
• @see — referência a outro elemento
\n
• @sample — inserção de um exemplo de código
\n
• @property — descrição de uma propriedade de classe
\n
• @constructor — descrição do construtor
\n
• @receiver — descrição do receptor para funções de extensão
\n

Exemplo de um comentário KDoc simples:

/**\n * Calcula o fatorial de um número dado.\n *\n * Usa uma abordagem iterativa para evitar estouro de pilha.\n * Funciona apenas com números inteiros não negativos.\n *\n * @param n Número inteiro não negativo para o qual o fatorial é calculado\n * @return Fatorial do número n (n!)\n * @throws IllegalArgumentException se n < 0\n */\nfun factorial(n: Int): Long {\n    require(n >= 0) { "n must be non-negative" }\n    var result = 1L\n    for (i in 2..n) {\n        result *= i\n    }\n    return result\n}

Documentando propriedades e classes

Para classes e propriedades, use a tag @property:

/**\n * Representa um usuário do sistema.\n *\n * @property id Identificador único do usuário\n * @property name Nome completo do usuário\n * @property email Endereço de e-mail\n * @property isActive Flag de atividade da conta\n */\ndata class User(\n    val id: Long,\n    val name: String,\n    val email: String,\n    val isActive: Boolean = true\n)

Geração de documentação com Dokka

Dokka é a ferramenta oficial para geração de documentação Kotlin. Ela suporta vários formatos de saída: HTML, Markdown, Javadoc e JSON. O Dokka consegue processar projetos multiplataforma e exibe corretamente construções específicas do Kotlin.

Configuração do Dokka no Gradle

Para adicionar o Dokka ao projeto, inclua o plugin no build.gradle.kts:

plugins {\n    id("org.jetbrains.dokka") version "1.9.20"\n}\n\ntasks.dokkaHtml {\n    outputDirectory.set(buildDir.resolve("dokka"))\n    moduleName.set("My Kotlin Library")\n}\n\ntasks.dokkaJavadoc {\n    outputDirectory.set(buildDir.resolve("javadoc"))\n}

Depois disso, execute o comando ./gradlew dokkaHtml — a documentação será gerada na pasta build/dokka.

Recursos avançados do Dokka

O Dokka suporta personalização da aparência, inclusão/exclusão de pacotes e adição de páginas extras. Exemplo de configuração com perso