Documentation
¶
Overview ¶
Package zipdoc extracts the documentation a service has already written — the doc comments on its typed handlers and on the fields of their In/Out types — and emits the zip.Describe calls that carry it into the OpenAPI spec and the MCP tool list at run time.
Go drops comments at compile time; reflection sees types and tags and never prose. So the ONLY way for a doc comment to reach the spec is a build-time pass over the AST, and this is it. cmd/zipdoc is the command around this package; the split is CLI (flags, files, exit codes) from extraction (source in, Doc out).
Index ¶
Constants ¶
const DefaultFile = "zipdoc_gen.go"
DefaultFile is the name written into each package's own directory, so the prose sits next to the source it came from and moves with it.
const Header = "// Code generated by zipdoc; DO NOT EDIT."
Header marks the emitted file. It is the standard form `go generate` and every Go tool recognises, and the guard that stops this command from ever writing over something a person wrote.
const ZipPkg = "github.com/zap-proto/zip"
ZipPkg is the package whose generic registrars this pass recognises. Matching on the import path rather than on the local name means an aliased import, a dot import and a plain one all resolve the same.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Op ¶
type Op struct {
Method string
Path string
Description string
Fields map[string]string
// Example and Response are compacted JSON, "" when the comment gave none.
Example string
Response string
}
Op is one typed registration and everything its source says about it. The fields mirror zip.Doc — emit.go writes them straight into a zip.Doc literal, and a test pins the two shapes together.
func (Op) Key ¶
Key is the operation's identity, the same one zip's registry uses. Key is the address half of the documentation key. The whole key also carries the declaring package, which Render adds — see [zip.DocKey] — because this map is one map for a process and an address is unique only within one app.
type Package ¶
type Package struct {
Dir string // directory the generated file belongs in
Name string // package clause
Path string // import path, so a package inside zip itself skips the import
Ops []Op
}
Package is one loaded package and the operations registered in it.
func Load ¶
Load type-checks the packages matched by patterns (relative to dir) and extracts every typed registration in them.
It insists the packages compile. Extraction reads resolved types — which generic instantiation a call is, which declaration a handler name refers to — so a package that does not type-check yields answers that are wrong rather than missing, and wrong is what this whole design exists to prevent.
func (Package) Render ¶
Render is the file for a package's operations, gofmt'd. Nil when the package registers nothing typed — there is no such thing as an empty documentation file, only one that should not exist.
Source Files