You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 52d89a0
Browse filesBrowse the repository at this point in the historyBrowse files
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>
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).
0 commit comments