Module doc_examples 

Doc-comment examples (#2461): a fenced bynk block in a doc comment is checked by bynk test, so an example cannot silently fall out of step with the code it documents. One marked bynk test also runs.

Each example of statements becomes a case in a synthetic suite targeting the unit that declares the doc comment, so it sees the unit’s scope and the ordinary test semantics. An example of declarations becomes a synthetic sibling commons that uses the declaring unit. A context cannot be usesd, so its declaration fence is checked in a synthetic copy of the context instead: the fence’s items are added to the copy, and one that redeclares a name the context already has replaces that declaration, so a doc showing type Order = … on type Order is no collision. Only the diagnostics inside the fence count. Each such fence is checked in its own project check (a layer holds the n-th such fence of every context), as two fences cannot share one copy of a context. The synthetic files are built in memory and added to the project’s source overlay. A first project check reports every diagnostic at the fence in the real file. A project that has bynk test examples is then compiled again with those cases added, so they are emitted and run like any other case.

Line-preserving. A synthetic file has exactly as many lines as the real file, and every line of an example’s body sits on the line it has in the real file, at the same column. The generated suite/case header is on the opening fence’s line. So a diagnostic or a failing expect names the right line and column in the real file, and only the file name needs mapping back.

Fence info strings. The first word is bynk; further words are separated by spaces or commas (bynk ignore and bynk,ignore are the same fence, matching the Book’s own examples). ignore, fragment and fail opt a fence out; test makes it a case that is run; any other fence (ts, text, …) is not Bynk and is not looked at.

Structs

DocExamples

The synthetic files for a project’s doc examples, and the means to report their diagnostics at the fences.

Functions

apply_aliases

Show the real file’s name in place of a synthetic one in text. Only a whole file name is replaced, never part of a longer one or of other text.

is_synthetic_path

Whether path is one of the synthetic files in aliases, by its whole name.