No exercício anterior, vimos que existem duas formas de escrever comentários em Go: comentários de uma linha, precedidos por //, e blocos de comentários multilinha, envolvidos por /* e */.
Comentários de documentação
Em Go, os comentários têm um papel importante na documentação do código.
Eles são usados pelo comando godoc, que extrai esses comentários para criar a documentação dos pacotes de Go.
Um comentário de documentação deve ser uma frase completa que começa com o nome da coisa que está sendo descrita e termina com um ponto final.
Os comentários devem vir antes dos pacotes e também dos identificadores exportados, por exemplo funções exportadas, métodos, variáveis de pacote, constantes e structs, que você vai conhecer melhor nos próximos exercícios.
Uma variável de nível de pacote pode se parecer com isto:
// TemperatureCelsius represents a certain temperature in degrees Celsius.
var TemperatureCelsius float64
Comentários de pacote
Os comentários de pacote devem ser escritos diretamente antes de uma cláusula package (package x) e começar com Package x ..., assim:
// Package kelvin provides tools to convert
// temperatures to and from Kelvin.
package kelvin
Comentários de função
O comentário de uma função deve ser escrito diretamente antes da declaração da função.
Ele deve ser uma frase completa que começa com o nome da função.
Por exemplo, um comentário exportado para a função Calculate deve ter a forma Calculate ....
Ele também deve explicar quais argumentos a função recebe, o que ela faz com eles e o que significam seus valores de retorno, terminando com um ponto final):
// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
return 0
}
Exercício de aprendizagem
