Documentação para pacotes privados
Go tem por padrão uma excelente forma de documentar pacotes, é possível gerar uma documentação detalhada usando apenas comentários no seu código e publicando em um repositório público.
Por exemplo, no código abaixo temos um pacote chamado mw que contém uma interface Middleware com comentário explicando o seu propósito, somente isso já é suficiente para gerar uma documentação.
// Middleware is a type that wraps an http.Handler
type Middleware interface {
Handle(http.Handler) http.HandlerFunc
}
Veja o resultado: https://pkg.go.dev/github.com/edmarfelipe/mw#Middleware
Repositórios privados
Mas e se o pacote for privado? Como gerar a documentação? infelizmente o pkg.go.dev não consegue acessar repositórios privados e para usar o godoc
é necessário rodar um servidor HTTP.
Para resolver esse problema de forma simples, podemos usar o gomarkdoc , que é uma command line que gera documentação em markdown a partir de comentários no código e não é possível.
Já que em todos os git hosts é possível visualizar arquivos markdown, podemos adicionar a documentação gerada no repositório e quem tiver acesso ao repositório poderá visualizar a documentação.
Como usar?
Para instalar é só rodar o comando:
go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest
E para gerar a documentação só é necessário executar o comando dessa forma:
gomarkdoc --output doc.md .
Onde --output é o arquivo de saída e . é o diretório onde está o código.
o resultado será um arquivo markdown com a documentação do pacote. por exemplo: doc.md
Conclusão
Com o gomarkdoc é possível gerar documentação para pacotes privados sem precisar de investir em uma solução mais complexa, como um servidor de documentação.
Por hoje é isso, espero que tenha gostado. Até a próxima!