go-documentationlisted

Use when writing or reviewing Go documentation — godoc comments on packages, types, functions, methods, sentinel errors; runnable Example tests; README/CONTRIBUTING/CHANGELOG. Covers the project-type detection (library vs application) that decides which docs are needed, comment grammar (start with name, full sentences), what to document vs what to skip, and Example test conventions. Apply proactively when introducing exported names, even if documentation was not requested.
muratmirgun/gophers · ★ 5 · Data & Documents · score 83

Install: claude install-skill muratmirgun/gophers

# 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). > Rea