Documente a API para as duas equipes
Escreva KDoc para que os desenvolvedores Android e iOS concordem sobre o uso
Documente a API para as duas equipes é uma aula grátis de Kotlin Multiplatform Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Kotlin Multiplatform Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Kotlin Multiplatform Academy inclui 4 aulas no total.
A Documentação Faz Parte da API
Desenvolvedores de Android e iOS chamam seu código compartilhado, portanto uma documentação clara é tão importante quanto as próprias funções. 📝
Conheça o KDoc
KDoc é o comentário de documentação do Kotlin. Você o escreve logo acima de uma declaração, e as ferramentas o transformam em páginas de referência legíveis.
/** Returns a friendly greeting for [name]. */
fun greet(name: String) = "Hi, " + nameExplique o Porquê
O código mostra o que acontece; uma boa documentação explica o porquê e o uso pretendido. Diga o que um chamador deve esperar, não como tudo funciona internamente.
Documente os Parâmetros
Use a anotação @param para descrever cada entrada. Assim, os chamadores dos dois aplicativos sabem exatamente o que passar sem ler o código-fonte.
/**
* @param rate tax rate as a fraction, like 0.2
*/Documente os Valores de Retorno
A anotação @return descreve o que é devolvido. Uma observação clara sobre o retorno evita suposições erradas sobre unidades, intervalos ou valores nulos.
/** @return total price including tax, never negative */Crie Links com Colchetes
Coloque nomes entre colchetes para criar links, como [Quote]. Os leitores vão diretamente para os tipos relacionados na documentação gerada.
/** Builds a [Quote] from a base price. */Mostre um Exemplo de Uso
Um pequeno exemplo é melhor que parágrafos de prosa. Um trecho que mostre uma chamada real responde à maioria das perguntas antes mesmo que sejam feitas.
Documente Apenas a API Pública
Concentre seu esforço na superfície pública. Os auxiliares internos podem receber poucos comentários, pois nenhuma equipe externa os chamará.
Pense em Quem Lê no iOS
Desenvolvedores Swift também leem seu KDoc, portanto descreva o comportamento em termos simples. Evite jargões da JVM que não significam nada no lado do iOS.
Gere Documentação com o Dokka
O Dokka lê seu KDoc e produz um site navegável. As duas equipes têm uma única referência compartilhada, em vez de precisarem adivinhar pelo código.
Mantenha a Documentação Sincronizada
Uma documentação desatualizada induz mais ao erro do que nenhuma documentação. Atualize o KDoc na mesma alteração que o código, para que os dois nunca divirjam.
Verificação Rápida
Vamos verificar seus conhecimentos sobre documentação.
Recapitulação
Escreva KDoc para sua API pública, explique o porquê, documente parâmetros e retornos, adicione um exemplo e deixe o Dokka compartilhá-lo com as duas equipes. 🎉
Perguntas Frequentes
A aula “Documente a API para as duas equipes” é grátis?
Sim — o texto completo de “Documente a API para as duas equipes” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Kotlin Multiplatform Academy, atualize para CoddyKit PRO. O curso de Kotlin Multiplatform Academy inclui 4 aulas no total.
O que vou aprender em “Documente a API para as duas equipes”?
Escreva KDoc para que os desenvolvedores Android e iOS concordem sobre o uso Você pratica Kotlin Multiplatform Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar Kotlin Multiplatform Academy?
Nenhuma experiência prévia é necessária. Kotlin Multiplatform Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.
Quanto tempo leva a aula “Documente a API para as duas equipes”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de Kotlin Multiplatform Academy?
Sim. Cada aula de Kotlin Multiplatform Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Projete uma API pública pequena
- Visibilidade internal versus pública
- Organize pacotes dentro do módulo
- Documente a API para as duas equipes