Mastering Go - Second Edition

Generating documentation

Go offers the godoc tool, which allows you to view the documentation of your packages – provided that you have included some extra information in your files.

The general advice is that you should try to document everything but leave out obvious things. Put simply, do not say, "Here, I create a new int variable." It would be better to state the use of that int variable! Nevertheless, really good code does not usually need documentation.

The rule about writing documentation in Go is pretty simple and straightforward: in order to document something, you have to put one or more regular comment lines that start with // just before its declaration. This convention can be used to document functions, variables, constants, ...