📖 2 min read (~ 400 words).

Maintainers

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

Looking up an option rather than an annotation? That moved: the Options reference lives under Usage, beside the flag and configuration-key spellings of the same knobs.

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.
  • 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.

  • How the three CLI tools are put together.

    Why there are three of them, where their shared flag surface is declared, and what keeps it whole.

  • What a scan costs, and what six months of work did to it.

    The two independent gains — the annotation parser and the package loader — measured on the same generated server, emitting the same document.

  • 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.
  • 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.
  • The commands — how the three CLI tools are put together: why each lives where it does, where their shared flag surface is declared, and what keeps it whole.
  • Performance — what a scan costs: what the grammar and the loader each changed since the code left go-swagger, and how the loader options compare warm and cold.