Once #69 is resolved, pkg.go.dev will render the GoDoc, but the root package's landing page will still be nearly empty:
doc.go is two lines ("Package chat provides a Go-native runtime for routing normalized chat events…").- The repository has no
Example… test functions, so pkg.go.dev shows no runnable examples.
docs/reference.md states that the API reference is the GoDoc, so this is the main reference surface for users.
Proposal
- Expand the root
doc.go into a package overview: the core model (adapter → event → thread → handler), a minimal construction snippet, dispatch modes, and pointers to docs/.
- Add a small number of
Example functions in example_test.go, for instance:
Example — construct a runtime with memory state and register OnNewMention.ExampleThread_Subscribe — subscribe on mention, reply in OnSubscribedMessage.ExampleRuntimeOptions_deferred — enable DispatchDeferred with a DetachTimeout.
They compile under go test (and go vet), so they cannot drift the way prose snippets can.
- Consider short package overviews for
state/redis, state/postgres, and state/nats (currently one line each).
Acceptance
Found during the docs audit behind #80, #81, and #82.
Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high
Once #69 is resolved, pkg.go.dev will render the GoDoc, but the root package's landing page will still be nearly empty:
doc.gois two lines ("Package chat provides a Go-native runtime for routing normalized chat events…").Example…test functions, so pkg.go.dev shows no runnable examples.docs/reference.mdstates that the API reference is the GoDoc, so this is the main reference surface for users.Proposal
doc.gointo a package overview: the core model (adapter → event → thread → handler), a minimal construction snippet, dispatch modes, and pointers todocs/.Examplefunctions inexample_test.go, for instance:Example— construct a runtime with memory state and registerOnNewMention.ExampleThread_Subscribe— subscribe on mention, reply inOnSubscribedMessage.ExampleRuntimeOptions_deferred— enableDispatchDeferredwith aDetachTimeout.They compile under
go test(andgo vet), so they cannot drift the way prose snippets can.state/redis,state/postgres, andstate/nats(currently one line each).Acceptance
go doc github.com/coder/chatshows an overview that a new user can act on.go test ./...compiles and runs the new examples; at least one has an// Output:line where practical.Found during the docs audit behind #80, #81, and #82.
Generated with
xum• Model:anthropic:claude-opus-5-5• Thinking:high