Note: when writing a comment for a package, regardless of its size, remember that the comment's first sentence is shown in godoc's package listing; so it's best for this sentence to be an accurate summary of the package's purpose and usage.

Documenting Known Bugs

Comments that aren't placed directly before any top-level declaration are not shown in godoc's output. There is, however, one important exception: top-level comments that start with BUG(who) are recognized as known bugs and are shown in the Bugs section of the package's documentation. The value of who should be the username of the person who can provide more information about that issue. For example, the following is a known bug in the bytes package:

Documenting Deprecated Code

Sometimes a field of a struct, a function, a data type, or even an entire package is no longer used or no longer needed, but it has to remain in place to preserve compatibility with older programs. In such cases, to indicate that an identifier should no longer be used, add a paragraph starting with Deprecated: to its documentation, followed by the reason or explanation for the deprecation, so it's shown in the documentation.

There are several simple rules that, if followed, make the documentation godoc produces more consistent in structure:

• Subsequent lines of text are treated as a continuation of the same paragraph; so to start a new paragraph you need to leave a blank line.
• Pre-formatted text should be written indented relative to the surrounding text (for an example, see the doc.go documentation in the gob package).
• URLs are automatically converted into HTML links and don't need any special markup.

The important thing is that none of these rules force you to do anything complicated or unusual. In fact, one of the strengths of godoc's simple approach is exactly this ease of use. That's why a large portion of Go code, including the entire standard library, follows these conventions. Your code, too, can produce proper documentation just by following these same simple commenting principles.

All Go packages located under $GOROOT/src/pkg, as well as packages in GOPATH workspaces, are accessible through godoc's command-line interface and HTTP interface. You can also use the -path flag to specify other paths to be indexed, or simply run the following command in your source folder:

Also, if you need the documentation to be served on a specific port, we can use the -http flag:

For more details, you can check the godoc documentation.

There's more detailed information about Go's documentation conventions, which you can find by checking the Go documentation.

Previous part: Introducing go fix | Golang basics