Go, al contrario que otros lenguajes, toma muy en serio la documentación. Y es que, según defienden sus creadores, la documentación es esencial para hacer un software accesible y mantenible. Mientras muchos desarrolladores abogan por separar el código de la documentación, la tónica generar en la comunidad de Go es que la documentación esté en el código fuente, de forma que sean todo uno.
Los comentarios en Go se hacen línea a línea precediendo la línea con // o escribir comentarios multilínea con "/*" para abrir el comentario y "*/" para cerrarlo.
La herramienta más utilizada para la documentación de código en Go es godoc. Es un paquete que se distribuye de forma independiente a los binarios. Para instalarlo, puedes ejecutar el siguiente comando:
$ go get golang.org/x/tools/cmd/godoc
Deberías documentar, al menos los paquetes, las constantes, las funciones y los tipos.
La convención que nos propone Godoc (y la comunidad) para documentar Go, es la siguiente: para documentar cosas tales como un tipo o una función simplemente escribe un comentario en la línea justo anterior. Es importante que además, añadas el nombre de lo que estás documentando como primer elemento de la oración. Esto permite a Godoc generar muchos tipos de documentación, como "man pages" para Unix (aunque lo más habitual es exportar la documentación a HTML). Por ejemplo:
// Foo ejecuta un ejemplo
func Foo(n int) int {
//CódigoUno de los errores más comunes a la hora de documentar código en Go, es dejar una línea entre el elemento a documentar y el comentario. En ese caso, godoc descartará el comentario como documentación.
También es importante que pienses en la longitud de tus comentarios, pues deben caber correctamente cuando los exportes, por ejemplo, a HTML. Especialmente, cuando estás documentando un paquete.
Si añades código, párrafos o enlaces dentro de tu documentación, godoc lo detectará automáticamente y lo formateará de la forma que estime más conveniente, sin necesidad de ningún tipo de intervención por parte del desarrollador.
Hay ocasiones en las que conocemos que nuestro código tiene un bug y necesitamos documentarlo, puedes hacerlo de la siguiente forma:
// BUG(persona): Información sobre el bugDonde "persona" es el nombre de aquella persona que puede proporcionar más información sobre el bug.
Otras veces hay documentar que un elemento de nuestro código va a dejar de estar incluido en futuras versiones. Para ello, añade "Deprecated" como primera palabra del comentario. Es decir:
// Deprecated: esto va a dejar de estar disponible a partir de la siguiente versiónComo puedes ver, con unas pocas sencillas reglas podemos hacer muchísimo, gastando más tiempo en escribir documentación que en formatearla.
Como se acaba de comentar, Go tiene su propio sistema de documentación con su propia sintaxis. Por tanto, no sería necesaria la utilización de Markdown o ningún otro lenguaje de marcas para documentar nuestro código en Go. Sin embargo, la utilización de un lenguaje como este puede ayudarnos a mejorar cómo esta documentación es mostrada.
En caso que queramos escribir con Markdown la documentación del código, podemos utilizar una plantilla para generarla. En GitHub hay bastantes ejemplos, pero también en muchos otros lugares con sólo buscar Godoc templates en Google.