document-go-apis

name	document-go-apis
description	Standard-library-style Go API documentation and comment conventions (TR-F024). Use when adding or changing exported Go identifiers, writing package comments, or backfilling godoc on a package so it reads like the Go standard library.

Skill: Document Go APIs (standard-library style)

Feature ID: TR-F024 | Milestone: M4 (M4.11 / M4.12)

When to use

• Adding or changing any exported Go identifier (func, type, method, const, var).
• Writing or updating a package comment (doc.go).
• Backfilling godoc on an existing package so it reads like the standard library.

The goal: a reader using go doc ./... or pkg.go.dev should understand the API without reading the implementation. Optimize for information value, not coverage theater.

Pre-research

go doc ./internal/radiusd                 # see how a package currently documents
view internal/radiusd/coa_service.go      # a well-documented reference in this repo
grep -rn "^// Package " internal pkg       # find existing package comments

Mirror the nearest well-documented neighbor; do not invent a new comment style.

Core conventions (godoc / stdlib)

1. Every exported identifier has a doc comment, and the comment starts with the identifier name:

   // CoAService sends RFC 5176 Dynamic Authorization (CoA / Disconnect) requests
   // to a NAS and reports a structured result.
   type CoAService struct { ... }
   
   // Disconnect sends a Disconnect-Request for the given session identity and
   // blocks until an ACK/NAK is received or the per-attempt timeout elapses.
   func (s *CoAService) Disconnect(ctx context.Context, ...) (*CoAResult, error) { ... }
   

2. Package comment: each non-main package has exactly one package comment, in a dedicated doc.go when it is more than a line. Start with // Package <name> ...:

   // Package radiusd implements the ToughRADIUS authentication, accounting,
   // and dynamic-authorization (CoA) protocol services.
   package radiusd
   

3. Full sentences, present tense, ending with a period. First sentence is a self-contained summary (it is what pkg.go.dev shows in lists). Keep the summary on the first line.
4. Document the contract, not the mechanics: parameters' meaning, return values, the zero value if it is usable, units (e.g. Kbps vs Mbps), ownership, and what counts as success vs failure.
5. Errors: state what error types / sentinel values callers should branch on (e.g. AuthError with a metrics tag). Wrap with %w and say so when relevant.
6. Concurrency: explicitly state whether a type/func is safe for concurrent use ("safe for concurrent use by multiple goroutines" or "not safe for concurrent use").
7. Context & blocking: note when a function blocks, honors ctx cancellation, performs I/O, or has timeout/retry semantics.
8. Runnable examples for non-trivial APIs: add Example<Name> functions in *_test.go (package <pkg>_test); they are compiled and run by go test and rendered on pkg.go.dev.
9. Deprecation: use a // Deprecated: use X instead. paragraph; do not delete the symbol abruptly.
10. Unexported code: comment only where the why is non-obvious (protocol quirks, vendor unit conversions, security-sensitive branches). Do not narrate obvious code.

Anti-patterns (reject these)

• // GetUser gets the user. — restates the name, zero information. Say what it loads, from where, and the failure mode.
• Comment that does not start with the identifier name (breaks godoc association).
• Per-line narration of self-evident statements.
• Documenting unexported helpers exhaustively while exported API stays bare.

How to check

go doc ./internal/<pkg>                     # read the rendered API; gaps are obvious
gofmt -l .                                  # comment formatting is part of gofmt
go vet ./...                                # catches some doc/format issues
go test ./...                              # compiles and runs Example functions
golangci-lint run                           # v2.12.2

Lint enforcement (incremental, M4.12): .golangci.yml currently disables the godoc checks (staticcheck ST1000 package-comment, ST1020/ST1021 func/type comment format). Do not flip them on globally in one shot — that would flag the whole tree. Backfill a package's docs first, then enable the relevant check (or revive's exported rule) scoped to that package, so the gate ratchets forward without a giant noisy diff.

Acceptance

• Every new/changed exported identifier has a doc comment that starts with its name and states the contract
• The package has a package comment (doc.go when multi-line)
• Units, error types to branch on, and concurrency safety are stated where they apply
• Non-trivial new APIs ship a runnable Example
• gofmt -l clean, go vet ./..., go test ./..., and golangci-lint run pass
• PR references TR-F024 (and the milestone subtask, e.g. M4.12, when backfilling)