Galera estou pesquisando sobre documentação no Kotlin. Efetivamente como realizar a documentação de um determinado app, percebi que se fala em KDoc, mas só encontro Javadoc na versão 3.0 do Android Studio. Vi também algo sobre Dokka, mas não ficou claro pra mim como funciona a documentação. Alguém sabe me dizer, como é na prática , e o que é oficial em relação a documentação no Kotlin?
1 Resposta
Javadoc
Definição 1
Javadoc é um programa muito parecido com um compilador que lê seus códigos e extrai certas partes dele para criar uma documentação muito útil na forma de páginas HTML. As páginas da API que você usa para o código java padrão são feitas usando Javadoc.
Ao analisar seu código, o Javadoc procura duas coisas: estrutura do código e comentários do Javadoc. A estrutura do código é apenas o próprio código. Isso é usado para construir a estrutura básica de uma página (ou seja, nome da classe, campos, métodos, etc.). Comentários Javadoc são comentários especiais que começam com /**
em vez do usual /*
(no que diz respeito ao compilador java normal, isto não faz diferença). Uma vez em um comentário do Javadoc, você escreve sobre o aspecto específico do código que está referenciando e pode usar tags HTML, bem como outras sintaxes especiais.
Definição 2
Sempre que você precisar procurar um método Java, pesquise no Google o nome do método e consulte as documentações para ver o que ele faz. Ótimo !
Mas como essas documentações foram criadas? Como foi gerada tanta documentação? Alguém foi contratado para fazer isso?
Bem, sempre que você escreve um código, é necessário explicá-lo adequadamente nos arquivos de código-fonte usando comentários. /** */
marca um bloco de comentários. Agora, o javadoc
é responsável por analisar esses comentários na documentação (cria arquivos HTML a partir desses comentários). Portanto, ninguém foi contratado, apenas o javadoc
foi executado.
Aqui está um exemplo de comentário inicial:
/**
* Nome da classe
* Informação da versão
* Nota de direitos autorais
*/
Mas isso não é tudo. javadoc
é muito poderoso. Ele permite que você escreva HTML básico dentro dos comentários e analisa o HTML para obter uma saída adequada. /** <html> */
É por isso que algumas páginas do Javadoc têm tabelas. Eles foram feitos usando as tags <td>
e <tr>
no HTML.
Por exemplo,
/**
* Primeiro parágrafo.
* <p> <ul>
* <li> o primeiro item
* <li> o segundo item
* <li> o terceiro item
* <ul> <p>
* Segundo parágrafo.
*/
Se você deseja que o javadoc funcione corretamente com seu código, siga a Convenção de Código Java: http://www.oracle.com/technetwork/java/codeconventions-150003.pdf se o código aderir à convenção, será fácil para o javadoc fazer a documentação.
Aqui está o guia oficial da Oracle para escrever comentários da documentação: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
Definição 3
Javadoc é um sistema extensível de geração de documentação que lê comentários especialmente formatados no código-fonte Java e gera documentação compilada. Geralmente, é usado para produzir documentação da API na forma de páginas da Web em HTML.
KDoc
Documentando o código Kotlin
A linguagem usada para documentar o código Kotlin (o equivalente ao JavaDoc do Java) é chamada KDoc. Na sua essência, o KDoc combina a sintaxe do JavaDoc para block tags (estendida para suportar construções específicas do Kotlin) e o Markdown para marcação no comentário.
Gerando a documentação
A ferramenta de geração de documentação da Kotlin é chamada Dokka.
O Dokka possui plugins para Gradle, Maven e Ant, para que você possa integrar a geração de documentação em seu processo de compilação.
Sintaxe do KDoc
Assim como no JavaDoc, os comentários do KDoc começam com /**
e terminam com */
. Cada linha do comentário pode começar com um asterisco, que não é considerado parte do conteúdo do comentário.
Por convenção, o primeiro parágrafo do texto da documentação é a descrição resumida do elemento, e o texto a seguir é a descrição detalhada.
Cada block tag começa em uma nova linha e começa com o caractere @
.
Aqui está um exemplo de uma classe documentada usando o KDoc:
/**
* A group of *members*.
*
* This class has no useful logic; it's just a documentation example.
*
* @param T the type of a member in this group.
* @property name the name of this group.
* @constructor Creates an empty group.
*/
class Group<T>(val name: String) {
/**
* Adds a [member] to this group.
* @return the new size of the group.
*/
fun add(member: T): Int { ... }
}
Para mais informações
https://kotlinlang.org/docs/reference/kotlin-doc.html
Artigos e Documentações que talvez possam ajudar
Javadoc Block Tags
https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-spec.html
JavaDoc – Implementando documentação através do NetBeans
https://www.devmedia.com.br/javadoc-implementando-documentacao-atraves-do-netbeans/2495
Gerar automaticamente a documentação do Kotlin Android com Dokka
https://medium.com/@julesrosser/auto-generate-kotlin-android-documentation-with-dokka-382248c03283
Kotlin/dokka: Mecanismo de documentação para Kotlin - GitHub
https://github.com/Kotlin/dokka
Bibliografia
https://stackoverflow.com/questions/19172015/what-exactly-is-javadoc