📖 2 min read (~ 400 words).

Maintainers

This section is the reference compendium: the precise, exhaustive description of the language codescan parses and the options that drive it. It is written for people who want the full contract — annotation authors looking up an exact rule, library callers looking up an option, and contributors porting, extending, or debugging the parser.

If you are learning codescan by example, start with the Tutorials instead — they show the same concepts as runnable Go with the spec they produce, side by side. The Annotation index cross-references every annotation to both its tutorial and its entry here.

The reference documents

  • The swagger:* annotation vocabulary: what each produces, where it attaches, and the keywords it admits.
  • The keyword: value forms recognised inside annotation blocks — grouped by class, with the annotation contexts that accept each one and its value shape.
  • Every field of codescan.Options — its type, default, and effect — grouped by concern and cross-linked to the how-to that shows it in action.
  • The smaller languages embedded in annotation bodies: the Parameters/Responses grammars, YAML surfaces, and prose classification.
  • The formal ISO-14977 EBNF the parser implements, from comment preprocessing through the typed walker.
  • Annotations — the swagger:* vocabulary: what each annotation does, where it attaches, its argument shape, and the keywords it admits. The author-facing normative reference.
  • Keywords — the per-keyword reference card: every keyword: value form, its value shape, and the contexts where it is legal.
  • Options — every field of codescan.Options: its type, default, and effect, cross-linked to the how-to that shows it in action. The library-caller reference.
  • Sub-languages — the smaller languages embedded inside annotation bodies (Parameters: / Responses: grammars, YAML surfaces, prose classification).
  • Grammar — the formal ISO-14977 EBNF the parser implements, from comment preprocessing through the typed walker.