go-documentation

Go Documentation

Documentation in Go is part of the API. Doc comments compile into go doc, pkg.go.dev, and IDE tooltips, so the rules exist to make those views readable. Code says what; comments say why, when, and what can go wrong.

Core Rules

1. Every exported name has a doc comment. Packages, types, functions, methods, constants, variables.
2. Doc comments start with the name (// Encode writes ...). Full sentences, capitalised, end with a period.
3. Document non-obvious behaviour. Restating the signature is noise.
4. Mark deprecations explicitly with a Deprecated: paragraph.
5. Examples are tests — runnable Example* functions in _test.go files with // Output: blocks are verified by go test.
6. Every package has exactly one package comment above the package clause in one file (doc.go if long).

What Project Are You Documenting?

Detect this first — it changes the doc surface area.

Signal	Project type	Docs to focus on
No main package, intended to be imported	Library	godoc, Example* tests, README usage examples, pkg.go.dev rendering
Has main package, cmd/ directory, ships a binary or Docker image	Application/CLI	Install instructions, --help text, config docs
Both (libraries that ship CLI tools)	Both	All of the above

Universal: doc comments on exported names, package comment, README, LICENSE, CONTRIBUTING (recommended), CHANGELOG (recommended).

Read references/godoc-grammar.md for the comment grammar, headings/lists, deprecation markers, and full examples.

Comment Grammar

// Encode writes the JSON encoding of req to w.
// It returns an error if req contains a non-serialisable field.
func Encode(w io.Writer, req *Request) error

Rules:

• Start with the name of the thing.
• Use a verb phrase for functions/methods, a noun phrase for types/values.
• Articles (A, An, The) may precede the name.
• Full sentences, punctuation included.
• Wrap at ~80 columns for diff comfort; no hard limit.