Go Documentation
Resource Routing
scripts/check-docs.sh - Run when checking exported functions, types, methods, constants, and packages for missing doc comments.scripts/check-docs-ast.go - Implementation helper invoked by check-docs.sh; patch this when changing documentation analysis behavior.assets/doc-template.go - Use when starting a documented package or exported API.references/CONVENTIONS.md - Read when documenting parameters, context behavior, concurrency safety, cleanup, errors, or named results.references/EXAMPLES.md - Read when adding runnable examples or package examples.references/FORMATTING.md - Read when formatting Godoc lists, paragraphs, links, and code blocks.
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
main packages, use the binary name: // The seed_generator command ...
- For long package comments, use a
doc.go file
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 correct errors.Is/errors.As
- Don't name results just to enable naked returns — clarity > brevity
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.
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
Example test 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
1---2name: go-documentation3description: Use when writing or reviewing documentation for Go packages, types, functions, or methods. Also use proactively when creating new exported types, functions, or packages, even if the user doesn't explicitly ask about documentation. Does not cover code comments for non-exported symbols (see go-style-core).4---5
6# Go Documentation
7
8## Resource Routing
9
10- `scripts/check-docs.sh` - Run when checking exported functions, types, methods, constants, and packages for missing doc comments.
11- `scripts/check-docs-ast.go` - Implementation helper invoked by `check-docs.sh`; patch this when changing documentation analysis behavior.
12- `assets/doc-template.go` - Use when starting a documented package or exported API.
13- `references/CONVENTIONS.md` - Read when documenting parameters, context behavior, concurrency safety, cleanup, errors, or named results.
14- `references/EXAMPLES.md` - Read when adding runnable examples or package examples.
15- `references/FORMATTING.md` - Read when formatting Godoc lists, paragraphs, links, and code blocks.
16
17---
18
19## Doc Comments
20
21> **Normative**: All top-level exported names must have doc comments.
22
23### Basic Rules
24
251. Begin with the name of the object being described
262. An article ("a", "an", "the") may precede the name
273. Use full sentences (capitalized, punctuated)
28
29```go
30// A Request represents a request to run a command.
31type Request struct { ...
32
33// Encode writes the JSON encoding of req to w.
34func Encode(w io.Writer, req *Request) { ...
35```
36
37Unexported types/functions with unobvious behavior should also have doc comments.
38
39> **Validation**: After adding doc comments, run `bash scripts/check-docs.sh` to verify no exported symbols are missing documentation. Fix any gaps before proceeding.
40
41---
42
43## Comment Sentences
44
45> **Normative**: Documentation comments must be complete sentences.
46
47- Capitalize the first word, end with punctuation
48- Exception: may begin with uncapitalized identifier if clear
49- End-of-line comments for struct fields can be phrases
50
51---
52
53## Comment Line Length
54
55> **Advisory**: Aim for ~80 columns, but no hard limit.
56
57Break based on punctuation. Don't split long URLs.
58
59---
60
61## Struct Documentation
62
63Group fields with section comments. Mark optional fields with defaults:
64
65```go
66type Options struct {
67 // General setup:
68 Name string
69 Group *FooGroup
70
71 // Customization:
72 LargeGroupThreshold int // optional; default: 10
73}
74```
75
76---
77
78## Package Comments
79
80> **Normative**: Every package must have exactly one package comment.
81
82```go
83// Package math provides basic constants and mathematical functions.
84package math
85```
86
87- For `main` packages, use the binary name: `// The seed_generator command ...`
88- For long package comments, use a `doc.go` file
89
90---
91
92## What to Document
93
94> **Advisory**: Document non-obvious behavior, not obvious behavior.
95
96| Topic | Document when... | Skip when... |
97|-------|-----------------|--------------|
98| Parameters | Non-obvious behavior, edge cases | Restates the type signature |
99| Contexts | Behavior differs from standard cancellation | Standard `ctx.Err()` return |
100| Concurrency | Ambiguous thread safety (e.g., read that mutates) | Read-only is safe, mutation is unsafe |
101| Cleanup | Always document resource release | — |
102| Errors | Sentinel values, error types (use `*PathError`) | — |
103| Named results | Multiple params of same type, action-oriented names | Type alone is clear enough |
104
105Key principles:
106
107- Context cancellation returning `ctx.Err()` is implied — don't restate it
108- Read-only ops are assumed thread-safe; mutations assumed unsafe — don't restate
109- Always document cleanup requirements (e.g., `Call Stop to release resources`)
110- Use pointer in error type docs (`*PathError`) for correct `errors.Is`/`errors.As`
111- Don't name results just to enable naked returns — clarity > brevity
112
113---
114
115## Runnable Examples
116
117> **Advisory**: Provide runnable examples in test files (`*_test.go`).
118
119```go
120func ExampleConfig_WriteTo() {
121 cfg := &Config{Name: "example"}
122 cfg.WriteTo(os.Stdout)
123 // Output:
124 // {"name": "example"}
125}
126```
127
128Examples appear in Godoc attached to the documented element.
129
130---
131
132## Quick Reference
133
134| Topic | Key Rule |
135|-------|----------|
136| Doc comments | Start with name, use full sentences |
137| Line length | ~80 chars, prioritize readability |
138| Package comments | One per package, above `package` clause |
139| Parameters | Document non-obvious behavior only |
140| Contexts | Document exceptions to implied behavior |
141| Concurrency | Document ambiguous thread safety |
142| Cleanup | Always document resource release |
143| Errors | Document sentinels and types (note pointer) |
144| Examples | Use runnable examples in test files |
145| Formatting | Blank lines for paragraphs, indent for code |
146
147---
148
149## Related Skills
150
151- **Naming conventions**: See [go-naming](../go-naming/SKILL.md) when choosing names for the identifiers your doc comments describe
152- **Testing examples**: See [go-testing](../go-testing/SKILL.md) when writing runnable `Example` test functions that appear in godoc
153- **Linting enforcement**: See [go-linting](../go-linting/SKILL.md) when using revive or other linters to enforce doc comment presence
154- **Style principles**: See [go-style-core](../go-style-core/SKILL.md) when balancing documentation verbosity against clarity and concision
om-scogo