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