Options reference

codescan.Options is the single configuration struct passed to codescan.Run. The zero value is a valid configuration — every flag defaults to false, every slice/map to nil, every numeric tunable to its built-in default. You set only what you need.

This page is the field-by-field catalogue. The godoc is the normative source; each field here links to the how-to guide that shows it on real input where one exists.

Note

codescan never writes to stdout or stderr. Every scan-time observation — a dropped construct, a rename, a prune — flows through the OnDiagnostic callback. See Diagnostics & observability below.

Inputs & scope

What gets loaded and which packages and types are in play. See Scope & discovery.

Option	Type	Default	Effect
`Packages`	`[]string`	`nil`	Package patterns to scan (e.g. `./...`), resolved relative to `WorkDir`.
`WorkDir`	`string`	`""` (cwd)	Working directory the package patterns and module resolution are rooted at.
`BuildTags`	`string`	`""`	Go build tags to activate while loading, so tag-guarded source is scanned. See Build tags.
`Include`	`[]string`	`nil`	Allow-list of package path patterns; when non-empty only matching packages are scanned. See Scoping the scan.
`Exclude`	`[]string`	`nil`	Deny-list of package path patterns, applied after `Include`. See Scoping the scan.
`IncludeTags`	`[]string`	`nil`	Allow-list filtering routes/operations by their swagger `tags`.
`ExcludeTags`	`[]string`	`nil`	Deny-list filtering routes/operations by their swagger `tags`.
`ExcludeDeps`	`bool`	`false`	Skip types reached through module dependencies, keeping the scan to first-party packages.
`ScanModels`	`bool`	`false`	Also emit a definition for every `swagger:model` type, not just route-reachable ones. See When the scanner emits a type.
`PruneUnusedModels`	`bool`	`false`	With `ScanModels`, drop discovered definitions not transitively reachable from a path, shared response/parameter, or `InputSpec` root. Runs before name reduction; `InputSpec` definitions are pinned. No-op without `ScanModels`. See Pruning unused models.
`InputSpec`	`*spec.Swagger`	`nil`	Base document to overlay scanned discoveries onto; its definitions are pinned and seed pruning roots. See Overlaying a spec.

Names & references

How definitions are named and how $refs render. See Names & $refs.

Option	Type	Default	Effect
`NameFromTags`	`[]string`	`nil` (⇒ `["json"]`)	Ordered struct-tag types a property/parameter/header name is derived from; first that supplies a name wins. Explicit empty slice ⇒ Go field name. Only the name — `json` encoding directives (`-`, `,omitempty`, `,string`) always come from `json`. See Naming from struct tags.
`SkipJSONifyInterfaceMethods`	`bool`	`false`	Emit interface-method property names verbatim (`ID`, `CreatedAt`) instead of auto-jsonifying them (`id`, `createdAt`). Only affects interface methods; struct fields and `swagger:name` overrides are unchanged. See Interface-method property names.
`RefAliases`	`bool`	`false`	Render Go type aliases as a first-class `$ref` (via `swagger:model`) instead of expanding them inline. See Alias rendering.
`TransparentAliases`	`bool`	`false`	Make aliases fully transparent — never creating a definition. See Alias rendering.
`DefaultAllOfForEmbeds`	`bool`	`false`	Render a plain (untagged, unnamed) struct embed as an `allOf` member — a `$ref` for a model embed, an inline member otherwise — with the embedding struct’s own fields in a sibling member, instead of inlining promoted properties. json-named embeds, `swagger:allOf` embeds, and interface embeds are unaffected. See Composing embeds with allOf.
`NameConcatBudget`	`float64`	`0` (⇒ `0.65`)	Readability cutoff `[0,1]` for the package-segment concatenation that deconflicts colliding definition names; lower scores are more readable. A group whose best concat scores above the budget is a candidate for the hierarchical fallback. See Resolving `$ref` name conflicts.
`EmitHierarchicalNames`	`bool`	`false`	For the rare collision group whose best flat concat exceeds `NameConcatBudget`, emit nested container definitions (`#/definitions/<pkg>/<Name>`) instead of a long flat concat, with an explanatory diagnostic. The always-correct flat concat is the default. See Resolving `$ref` name conflicts.
`EmitRefSiblings`	`bool`	`false`	Emit a `$ref`’d field’s description and vendor extensions as direct `$ref` siblings (`{$ref, description, x-*}`) instead of an `allOf` wrap. Validations/externalDocs still force a compound. See Descriptions beside a `$ref`.
`SkipAllOfCompounding`	`bool`	`false`	Never emit an `allOf` compound for a `$ref`’d field. Validations/externalDocs are dropped (description/extensions too, unless `EmitRefSiblings` keeps them as siblings); each drop raises a diagnostic. `required` is unaffected. See Descriptions beside a `$ref`.
`DescWithRef`	`bool`	`false`	Deprecated — prefer `EmitRefSiblings`. In the description-only case, wrap the `$ref` in a single-arm `allOf` to preserve the description (strict draft-4 shape). No-op when `EmitRefSiblings` is set. See Descriptions beside a `$ref`.

Titles & descriptions

The human-readable text the spec carries. See Titles & descriptions.

Option	Type	Default	Effect
`SingleLineCommentAsDescription`	`bool`	`false`	Route every single-line doc comment to `description`, never to `title`/`summary` (the first-sentence convention otherwise applies). Multi-line comments keep the title/description split. See Single-line comments as descriptions.
`AfterDeclComments`	`bool`	`false`	Let swagger annotations live inside a struct body or as a trailing comment, in addition to the doc comment above the declaration, so the godoc stays clean. v0.36 scope: type declarations (struct inside-body + alias trailing comment). See Keeping annotations out of the godoc.
`CleanGoDoc`	`bool`	`false`	Strip godoc doc-link brackets from generated `title`/`description` (humanizing unresolved ones, dropping reference-definition lines, recomposing resolved links to each schema’s exposed name). Applies only to godoc-derived prose; overrides are untouched. See Cleaning godoc doc-links.

Field types, formats & extensions

How an individual property renders. See Field types & formats.

Option	Type	Default	Effect
`SetXNullableForPointers`	`bool`	`false`	Emit `x-nullable: true` on pointer-typed fields. See Nullable pointers.
`SkipExtensions`	`bool`	`false`	Suppress all `x-go-*` vendor extensions in the output. See Vendor extensions.
`EmitXGoType`	`bool`	`false`	Stamp an `x-go-type` extension (fully-qualified originating Go type) on every emitted definition, for round-tripping a spec back to its Go types. Suppressed under `SkipExtensions`. See Vendor extensions.
`SkipEnumDescriptions`	`bool`	`false`	Keep the per-enum-value const-name mapping (from `swagger:enum`) out of the `description`, exposing it only via the `x-go-enum-desc` extension. Suppressed entirely under `SkipExtensions`.

Diagnostics & observability

Channels for what the scan observed; these do not change the output spec.

Option	Type	Default	Effect
`OnDiagnostic`	`func(Diagnostic)`	`nil`	Invoked once per diagnostic in source order (parser warnings, validation failures, prunes, renames). Diagnostics never block the build — invalid constructs are dropped from the spec while their explanation flows here. The only output channel. Experimental while LSP integration matures.
`OnProvenance`	`func(Provenance)`	`nil`	Invoked once per anchor node in the produced spec, carrying its JSON pointer and the source position of the Go construct that produced it. Never blocks the build. Experimental while LSP/TUI integration matures.
`Debug`	`bool`	`false`	Deprecated, ignored. The legacy stderr debug logger was retired; wire `OnDiagnostic` instead. Retained for API compatibility.