0

Usando KDoc para comentar e documentar projetos

#Kotlin
Deyvson Aguiar
Deyvson Aguiar

Olá digionautas!


Estou de volta com mais um artigo da minha jornada no Bootcamp Everis Kotlin Developers. E quero dizer que está sendo um verdadeiro desafio. Principalmente agora, que cheguei ao módulo 7: "Fundamentos de Orientação a Objetos com Kotlin". Bem, como o título já diz, quero compartilhar com vocês sobre como começar a realizar comentários e gerar uma mini-documentação no próprio código.


Primeiro seguem as vantagens. Ter na sua classe, comentários sobre os parâmetros, propriedades e o que faz cada trecho do seu código é de extrema importância e mostra o nível de organização de todo programador. Trechos bagunçados são difíceis de serem avaliados. Principalmente o digionauta que me lê e está passando por uma avaliação nos seus estudos para um estágio ou vaga de emprego. Bem, se vocês verem alguma desvantagem é só comentar abaixo.


Na documentação oficial do Kotlin aqui, é possível perceber a semelhança com o sistema de documentação do Java, o JavaDoc. Mas temos uma simplicidade maior quando se trata do KDoc, como o uso do markdown, por exemplo. No noss caso vamos nos ater ao básico.


Usamos os caracteres "/**" + Enter para escrever um comentário longo. No início de uma classe e acima de todo o código, por exemplo, descrevemos organizadamente o nosso código com a descrição do que faz essa classe. Ou um comentário simplista apenas, como no exemplo da documentação:

/**
 * 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 { ... }
}


Hipoteticamente, o exemplo traz na primeira frase, um título da classe. Na segunda sentença, o que esta classe faz. De forma fácil após o /** a sua IDE geralmente irá completar com o fechamento */ numa nova linha e entenderá que ali você iniciou um novo comentário. Cada Enter corresponde automaticamente a uma nova linha de comentário (mantenha tudo organizado e espaçado).


Então, existem três tipos de comentário importantíssimos que foram iniciados com o caracter "@", que faz parte da sintaxe do sistema de comentários de sua IDE. Eu utilizo o IntellliJ IDEA 2020.3 que já vem por padrão a biblioteca do KDoc que entenderá a atribuição específica do comentário:

@param <name> - Se sua classe tem um parâmetro, especifique-o em uma nova linha, substituindo o <name> pelo nome do seu parâmetro case sentitive. Após isso, você poderá explicar que parâmetro esse ou deixar uma mensagem curta na mesma linha

@property <name> - novamente, substitua o <name> pelo nome da propriedade da sua classe. Linha por linha cada atributo ou, encadeando na mesma linha como na linguagem que você está programando, como iterar o atributo. Exemplo: [Pessoa.nome], [Pessoa.numero] Para saber mais sobre esse encadeamento consulte a documentação ao final do artigo.

@constructor - comente sobre o uso de um construtor primário ou secundário


Estamos quase no fim, relaxa! Falta falarmos sobre como comentar funções dentro de nossa classe. Bem, muito fácil. É só uma linha acima da função você abrir um novo espaço e setar um novo comentário /** + Enter e então dizer para que serve sua função, descrever como ensinei acima quais parâmetros ela espera receber e o tipo de retorno em uma nova linha com @return e descrever na mesma linha que tipo de retorno será aguardado.


Não esqueçamos que para cada ação, poderemos usar comentários simples com um "//" e descrever resumidamente o que determinado trecho de código, por exemplo, realiza.


Para se aprofundar e tirar dúvidas sugiro a documentação oficial:

https://kotlinlang.org/docs/kotlin-doc.html?q=it#kdoc-syntax

Exemplo de código comentado com KDoc

https://github.com/deyvsonaguiar/digionebank

0
19

Comentários (0)

Pernambucano, 35 anos. Solteiro, com o objetivo de dar upgrade na carreira e mudar de vida!

Brasil