The documentation of an exported type should start with the type’s name GO-D5002
Documentation
Minor
6 months ago
—
8 months old
comment on exported type SafeURIParser should be of the form "SafeURIParser ..." (with optional leading article)
21 GetEndpointPath(string, []string) string
22}
23
24// Like URIParser but with safe versions of the clean host functionality that 25// does not panic but returns an error.
26type SafeURIParser interface {
27 SafeCleanHosts([]string) ([]string, error)
Description
Doc comments work best as complete sentences, which allow a wide variety of automated presentations. The first sentence should be a one-sentence summary that starts with the name being declared.
If every doc comment begins with the name of the item it describes, you can use the doc subcommand of the go tool and run the output through grep.
See https://golang.org/doc/effective_go.html#commentary for more information on how to write good documentation.
Bad practice
package main
// This struct represents an cybernetically enhanced duck
type Duck struct {
}
Recommended
package main
// Duck represents an cybernetically enhanced duck
type Duck struct {
}