Skip to content

Commit 52d89a0

Browse files
fredbiclaude
andcommitted
docs(scanner): document AfterDeclComments; alias coverage; defer const-enum
close-out of AfterDeclComments. - scanner/README.md §after-decl: the two enrichment targets (EntityDecl.Comments vs the Field.Doc mutation), the leading-body-comment rule, idempotency guard, routes/operations already-agnostic, and the out-of-scope notes. - fixture: a `stampType` type-alias case (`type Stamp = string // swagger:model stampType`) confirming Phase A's TypeSpec.Comment path covers inlined aliases. - const-enum (`const X = … // swagger:enum`) is deliberately NOT supported: swagger:enum is type-based (resolves a type, collects its consts), so a lone const has no builder semantics and supporting it would break the scanner-only constraint. Documented in the README and design doc. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
1 parent fbc47b6 commit 52d89a0

4 files changed

Lines changed: 55 additions & 0 deletions

File tree

‎fixtures/enhancements/after-decl-comments/api.go‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@ type Widget struct {
2626
// Count is a plain count. Clean godoc above; annotation inlined below.
2727
type Count int // swagger:model countType
2828

29+
// Stamp is a string alias. Clean godoc above; annotation inlined trailing.
30+
type Stamp = string // swagger:model stampType
31+
2932
// ListWidgets is an ordinary Go handler with a clean godoc.
3033
func ListWidgets() {
3134
// swagger:route GET /widgets widgets listWidgets

‎fixtures/integration/golden/enhancements_after_decl_comments.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,12 @@
2727
"x-go-name": "Count",
2828
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/after-decl-comments"
2929
},
30+
"stampType": {
31+
"type": "string",
32+
"title": "Stamp is a string alias. Clean godoc above; annotation inlined trailing.",
33+
"x-go-name": "Stamp",
34+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/after-decl-comments"
35+
},
3036
"widgetModel": {
3137
"description": "Widget is exposed to API consumers.",
3238
"type": "object",

‎internal/integration/coverage_after_decl_comments_test.go‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,10 @@ func TestCoverage_AfterDeclComments_On(t *testing.T) {
5656
require.MapContainsT(t, doc.Definitions, "countType")
5757
assert.SliceContainsT(t, doc.Definitions["countType"].Type, "integer")
5858

59+
// type alias inlined trailing: swagger:model stampType
60+
require.MapContainsT(t, doc.Definitions, "stampType")
61+
assert.SliceContainsT(t, doc.Definitions["stampType"].Type, "string")
62+
5963
// route inside the func body is discovered (location-agnostic today).
6064
require.NotNil(t, doc.Paths)
6165
require.MapContainsT(t, doc.Paths.Paths, "/widgets")

‎internal/scanner/README.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ parameters, responses) consumed by the builder layer.
2424
pure read vs implicit registration
2525
- [§classifier](#classifier) — `detectNodes` bitmask semantics and
2626
struct-annotation exclusivity
27+
- [§after-decl](#after-decl) — `AfterDeclComments` — reading annotations
28+
inside / below a declaration
2729
- [§quirks-open](#quirks-open) — deferred follow-ups
2830

2931
---
@@ -232,6 +234,46 @@ that downstream builders parse out of the comment block directly.
232234
(`title` / `description` are the godoc title/description overrides; see
233235
the schema builder's [§user-overrides](../builders/schema/README.md#user-overrides).)
234236

237+
## <a id="after-decl"></a>§after-decl — `AfterDeclComments`
238+
239+
`Options.AfterDeclComments` (opt-in, default false) lets swagger annotations
240+
live **inside** a declaration or **inlined** as a trailing comment, so the godoc
241+
*above* the declaration stays clean and human-facing. It is **solely a scanner
242+
concern** — the located comments are folded into the comment source the builders
243+
already consume (`EntityDecl.Comments` and `ast.Field.Doc`), so the grammar and
244+
builders are untouched. Same annotation grammar, no new syntax.
245+
246+
What the scanner folds, by shape (`index.go`):
247+
248+
| Shape | Folded comment | Into |
249+
|---|---|---|
250+
| struct type | leading body comment groups (after `{`, before the first field, excluding any field `.Doc`) — `leadingBodyComments` | a fresh merged `EntityDecl.Comments` (`ts.Doc` untouched) |
251+
| alias / non-struct type | trailing `TypeSpec.Comment` (`type X = Y // swagger:model …`) | same |
252+
| struct field | trailing `Field.Comment` (`B string // swagger:strfmt date`) — `enrichStructFields` | the shared `Field.Doc` (the one mutation, see below) |
253+
254+
The clean godoc above still provides the title/description: the merged group is
255+
`docAbove ++ located`, and because positions stay ascending (doc above < the
256+
inside/trailing comment below), the grammar reconstructs a blank-line gap and
257+
parses it without change. Discovery works because `detectNodes` already scans
258+
every `file.Comments` group (the file bitmask flips), and the merged
259+
`EntityDecl.Comments` makes the per-decl `HasModelAnnotation` gate pass.
260+
261+
**Idempotency.** Decl-level folding is pure construction — `ts.Doc` is never
262+
mutated, so re-processing is safe with no guard. Field-level folding is the only
263+
place the shared AST is mutated (`Field.Doc` is repointed to the merged group),
264+
guarded by `TypeIndex.enrichedFields` so a field is rewritten at most once.
265+
266+
**Routes / operations** are already position-agnostic
267+
(`collectRoute/OperationPathAnnotations` scan all `file.Comments`), so a
268+
`swagger:route` inside a func body is discovered with or without this option.
269+
270+
**Out of scope.** A standalone `const X = … // swagger:enum`: `swagger:enum` is
271+
type-based (it resolves a *type* and collects that type's consts via
272+
`FindEnumValues`), so a lone const is not an enum carrier and has no builder
273+
semantics today. Supporting it would mean new builder behaviour, which this
274+
scanner-only feature deliberately avoids. Nested/anonymous inline structs are
275+
likewise not enriched (only named struct type decls are walked).
276+
235277
## <a id="quirks-open"></a>§quirks-open — deferred follow-ups
236278

237279
- **`FindModel` deprecation.** The deprecated alias is still on the

0 commit comments

Comments
 (0)
⌂ 换网址