Go Documentation
Available Scripts
scripts/check-docs.sh— Reports exported functions, types, methods, constants, and packages missing doc comments. Runbash scripts/check-docs.sh --helpfor options.
See assets/doc-template.go when writing doc comments for a new package or exported type and need a complete reference of all documentation conventions.Doc Comments
Normative: All top-level exported names must have doc comments.
Basic Rules
- Begin with the name of the object being described
- An article ("a", "an", "the") may precede the name
- Use full sentences (capitalized, punctuated)
// A Request represents a request to run a command.
type Request struct { ...
// Encode writes the JSON encoding of req to w.
func Encode(w io.Writer, req *Request) { ...Unexported types/functions with unobvious behavior should also have doc comments.
Validation: After adding doc comments, run bash scripts/check-docs.sh to verify no exported symbols are missing documentation. Fix any gaps before proceeding.Comment Sentences
Normative: Documentation comments must be complete sentences.
- Capitalize the first word, end with punctuation
- Exception: may begin with uncapitalized identifier if clear
- End-of-line comments for struct fields can be phrases
Comment Line Length
Advisory: Aim for ~80 columns, but no hard limit.
Break based on punctuation. Don't split long URLs.
Struct Documentation
Group fields with section comments. Mark optional fields with defaults:
type Options struct {
// General setup:
Name string
Group *FooGroup
// Customization:
LargeGroupThreshold int // optional; default: 10
}Package Comments
Normative: Every package must have exactly one package comment.
// Package math provides basic constants and mathematical functions.
package math- For
mainpackages, use the binary name:// The seed_generator command... - For long package comments, use a
doc.gofile
Read references/EXAMPLES.md when writing package-level docs, main package comments, doc.go files, or runnable examples.
What to Document
Advisory: Document non-obvious behavior, not obvious behavior.
| Topic | Document when... | Skip when... |
|---|---|---|
| Parameters | Non-obvious behavior, edge cases | Restates the type signature |
| Contexts | Behavior differs from standard cancellation | Standard ctx.Err() return |
| Concurrency | Ambiguous thread safety (e.g., read that mutates) | Read-only is safe, mutation is unsafe |
| Cleanup | Always document resource release | — |
| Errors | Sentinel values, error types (use *PathError) | — |
| Named results | Multiple params of same type, action-oriented names | Type alone is clear enough |
Key principles:
- Context cancellation returning
ctx.Err()is implied — don't restate it - Read-only ops are assumed thread-safe; mutations assumed unsafe — don't restate
- Always document cleanup requirements (e.g.,
Call Stop to release resources) - Use pointer in error type docs (
*PathError) for correcterrors.Is/errors.As - Don't name results just to enable naked returns — clarity > brevity
Read references/CONVENTIONS.md when documenting parameter behavior, context cancellation, concurrency safety, cleanup requirements, error returns, or named result parameters in function doc comments.
Runnable Examples
Advisory: Provide runnable examples in test files (*_test.go).func ExampleConfig_WriteTo() {
cfg := &Config{Name: "example"}
cfg.WriteTo(os.Stdout)
// Output:
// {"name": "example"}
}Examples appear in Godoc attached to the documented element.
Read references/EXAMPLES.md when writing runnable Example functions, choosing example naming conventions (Example vs ExampleType_Method), or adding package-level doc.go files.
Godoc Formatting
Read references/FORMATTING.md when formatting godoc headings, links, lists, or code blocks, using signal boosting for deprecation notices, or previewing doc output locally.
Quick Reference
| Topic | Key Rule |
|---|---|
| Doc comments | Start with name, use full sentences |
| Line length | ~80 chars, prioritize readability |
| Package comments | One per package, above package clause |
| Parameters | Document non-obvious behavior only |
| Contexts | Document exceptions to implied behavior |
| Concurrency | Document ambiguous thread safety |
| Cleanup | Always document resource release |
| Errors | Document sentinels and types (note pointer) |
| Examples | Use runnable examples in test files |
| Formatting | Blank lines for paragraphs, indent for code |
Related Skills
- Naming conventions: See go-naming when choosing names for the identifiers your doc comments describe
- Testing examples: See go-testing when writing runnable
Exampletest functions that appear in godoc - Linting enforcement: See go-linting when using revive or other linters to enforce doc comment presence
- Style principles: See go-style-core when balancing documentation verbosity against clarity and concision