Documentação em Kotlin: escrevendo código que fala por si só

Documentação em projetos Kotlin: a arte de ser compreendido

Imagine: você abre um projeto Kotlin de outra pessoa. O código é bonito, conciso, mas... você não entende para que serve aquela função e o que ela retorna. Familiar? Agora imagine que este projeto é seu, mas seis meses depois. A documentação em Kotlin não é apenas uma cortesia para os colegas. É um investimento no futuro do seu código.

Neste artigo, vamos explorar as melhores práticas de documentação de projetos Kotlin. Você aprenderá a usar KDoc, Dokka e comentários simples para que seu código fale por si só. Vamos lá!

Por que a documentação em Kotlin não é chata?

Kotlin é uma linguagem criada para pessoas. Ela é legível como inglês e sua sintaxe elimina código boilerplate. Mas mesmo o código mais elegante pode ser um mistério sem documentação. Especialmente quando se trata de:

\n
• Lógicas de negócio complexas;
\n
• Bibliotecas e APIs usadas por outros desenvolvedores;
\n
• Projetos Android com ciclo de vida longo;
\n
• Soluções corporativas onde a rotatividade de pessoal é normal.
\n

Uma boa documentação Kotlin resolve três tarefas: explica "o que" o código faz, "por que" ele faz isso e "como" usá-lo. Sem ela, você corre o risco de ter um código que ninguém quer tocar (nem você mesmo).

KDoc: a principal ferramenta de documentação do Kotlin

KDoc é o equivalente ao JavaDoc para Kotlin. Ele usa comentários no formato /** ... */ e suporta Markdown. É o padrão de facto para documentação em projetos Kotlin.

Aqui está um exemplo básico:

/**\n * Calcula o desconto para um usuário com base em seu status.\n *\n * @param price Preço original do produto.\n * @param userLevel Nível do usuário (BRONZE, SILVER, GOLD).\n * @return Preço final com desconto.\n * @throws IllegalArgumentException Se price for negativo.\n */\nfun calculateDiscount(price: Double, userLevel: UserLevel): Double {\n    // lógica\n}

Observe: KDoc usa as tags @param, @return, @throws. Mas, diferentemente do JavaDoc, você pode escrever Markdown diretamente dentro do comentário. Isso é útil para listas, links e formatação.

Melhores práticas do KDoc

\n
• Escreva para pessoas, não para máquinas. Não duplique o que é óbvio no código. Em vez de // define o valor, escreva // Define o valor que será usado no cálculo de impostos.
\n
• Documente a API pública. Funções internas (private ou internal) podem ser documentadas de forma resumida ou nem documentadas.
\n
• Use @see e @sample. Faça referência a funções relacionadas ou exemplos de uso.
\n
• Não se esqueça do @receiver para funções de extensão.
\n

Dokka: transformando comentários em documentação bonita

Dokka é um gerador de documentação para Kotlin. Ele pode criar HTML, Markdown, JavaDoc e até documentação para projetos multiplataforma. Se você escreve uma biblioteca ou trabalha em equipe, Dokka é seu melhor amigo.

A instalação é simples. No build.gradle.kts, adicione o plugin:

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

Em seguida, execute o comando:

./gradlew dokkaHtml

O Dokka gerará uma pasta build/dokka/html com uma documentação bonita, incluindo todos os seus comentários KDoc, hierarquia de classes e até links para os fontes.

Dicas sobre Dokka

\n
• Configure o logotipo e a descrição do projeto em dokkaConfiguration;
\n
• Use @suppress para ocultar elementos indesejados