go-documentation

---
name: go-documentation
description: Use when writing or reviewing Go doc comments, or creating exported types, functions, or packages even without a documentation request. Internal code comments belong to go-style-core.
allowed-tools: Bash(bash:*)
---

# Go Documentation

> Compatibility: Baseline Go 1.27 (see `COMPATIBILITY.md`). `go doc -ex` and
> `go doc <pkg>@<version>` require Go 1.27+; doc links and `#` headings Go 1.19+.

## 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

1. Begin with the name of the object being described
2. An article ("a", "an", "the") may precede the name
3. Use full sentences (capitalized, punctuated)

```go
// 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**: `scripts/check-docs.sh` lists exported symbols without a doc comment, outside `package main` and skipping methods of unexported types and standard methods such as `Error` and `ServeHTTP`, as `revive` does; it runs with the [go-linting](../go-linting/SKILL.md) gate, once, at the end of the task.

---

## 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:

```go
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.

```go
// 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.AsType`
- Don't name results just to enable naked returns — clarity > brevity

---

## Runnable Examples

> **Advisory**: Provide runnable examples in test files (`*_test.go`).

```go
func ExampleConfig_WriteTo() {
    cfg := &Config{Name: "example"}
    cfg.WriteTo(os.Stdout)
    // Output:
    // {"name": "example"}
}
```

Examples appear in Godoc attached to the documented element. `go doc -ex
<symbol>` (Go 1.27+) lists them from the terminal, and `go doc <pkg>@<version>`
(Go 1.27+) reads the docs of a version you have not imported.

---

## Related Skills

- [go-naming](../go-naming/SKILL.md): the identifiers the comments describe.
- [go-testing](../go-testing/SKILL.md): runnable `Example` functions.
- [go-linting](../go-linting/SKILL.md): linters that enforce doc comment presence.
- [go-style-core](../go-style-core/SKILL.md): verbosity against clarity and concision.