Overview
Comments on package declarations should provide general package documentation. These comments can be short, like the sort package’s brief description:
// Package sort provides primitives for sorting slices and user-defined
// collections.
package sort
They can also be detailed like the gob package’s overview. That package uses another convention for packages that need large amounts of introductory documentation: the package comment is placed in its own file, doc.go, which contains only those comments and a package clause.
When writing package comments of any size, keep in mind that their first sentence will appear in godoc’s package list.
Comments that are not adjacent to a top-level declaration are omitted from godoc’s output, with one notable exception. Top-level comments that begin with the word "BUG(who)” are recognized as known bugs, and included in the “Bugs” section of the package documentation. The “who” part should be the user name of someone who could provide more information. For example, this is a known issue from the bytes package:
// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
Sometimes a struct field, function, type, or even a whole package becomes redundant or unnecessary, but must be kept for compatibility with existing programs. To signal that an identifier should not be used, add a paragraph to its doc comment that begins with “Deprecated:” followed by some information about the deprecation.
Demo
It runs as a web server and presents the documentation as a web page.
$ godoc -http=:6060