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