routerdoc

Overview ¶

Command routerdoc lifts each hand-written route's sentence out of the Go doc comment on the handler it names, into routers/wired_gen.go.

go run ./cmd/routerdoc            # write routers/wired_gen.go
go run ./cmd/routerdoc -verify    # fail if it would differ

Why a build-time pass and not a table ¶

Go DROPS COMMENTS AT COMPILE TIME, so a running program cannot read the sentence its own handler was documented with. Every projection that needs one — the published OpenAPI document, the MCP tool list, the generated SDKs, the CLI's help — therefore either gets it lifted before the build or gets it from a second place. A second place is the disease: prose written beside the route drifts from the handler it describes, silently, in the direction that hurts, because the spec is what customers believe.

So the sentence has ONE home — the doc comment on the handler — and this reads it there. `App.Router(path, &controllers.X{}, "GET:Fn")` already names the handler, machine-readably, in the same call that names the address; nothing new is declared and there is nothing to keep in step.

It is the same law hanzoai/cloud's zipdoc obeys for typed zip handlers, and the same identifier strip: Go's "Fn does X" convention is right for godoc and noise in a description projected out of Go's namespace.

What it reads, and what it refuses ¶

Only calls whose path and method-spec are STRING LITERALS: the resource table in routers/resources.go computes both, and its surface is already described by routers/openapi.go from that same table. A route that is registered but whose handler has no doc comment is a build failure naming the file, because a published operation that says nothing about itself is exactly what this exists to prevent, and only the person writing the handler can fix it.