Shaping the output

The same annotated Go can render into the spec in more than one shape, and a handful of codescan.Options (plus a few field-level annotations) let you choose. The guides are grouped by what they shape:

• Scope & discovery — which packages are read and which types become definitions.
• Names & $refs — the names definitions are published under and how references render.
• Titles & descriptions — the human-readable text the spec carries.
• Field types & formats — how an individual property renders.
• Response bodies — describing a payload without a dedicated swagger:response struct.

• Scope & discovery

  Choose what gets scanned and which definitions land in the spec — package patterns and filters, when a type is emitted, pruning unreferenced models, overlaying an existing document, and build constraints.
• Names & $refs

  Control the names definitions are published under and how references render — deconflicting collisions, deriving member names from struct tags, alias rendering, and a description sitting beside a $ref.
• Titles & descriptions

  Shape the human-readable text — override godoc with API-facing title and description, route single-line comments to the description, keep annotations out of the godoc, and clean godoc doc-links out of generated prose.
• Field types & formats

  Tune how an individual field renders — force a conformant format, mark pointer fields nullable, and control the x-go-* vendor extensions codescan emits.
• Response bodies

  Describe a concrete response payload without a dedicated swagger:response struct — declare the body inline on the route, or shadow a generic envelope’s payload with a doc-only struct.

Each guide is task-oriented — “I want the output to look like this” — and shows the same input rendered both ways, as before/after golden output the example tests verify. For the field-by-field meaning of every option, see the Options reference or the Options godoc.