`examples/README.md`'s Demonstrates column has drifted and is not gated
documentationtesting
Two rows in `examples/README.md` credit examples with builtins they do not call.
- `string_ops.vera` is described as demonstrating "String search, transform, split, join". Neither `string_split` nor `string_join` appears in the file (they are exercised elsewhere — `examples/life.vera` and `examples/sqlitedb.vera`). It actually calls `string_slice`, `string_strip`, `string_concat`, `string_char_code` and `string_length`.
- `array_utilities.vera` is described as demonstrating `array_slice`. `array_slice` does not appear in the file — or anywhere in `examples/` at all. The file does call `array_fold`, which the row omits.
## Root cause
`scripts/check_examples_readme.py` validates the **Run** column only. Its docstring is explicit: it extracts the `vera run` command, checks the file exists, and checks the `--fn` target is a `public fn` in that file. Nothing checks the Demonstrates column, so that column has never been gated and has drifted unnoticed.
## Why this matters
The Demonstrates column is the index a reader uses to find the example for a given builtin, so a wrong entry sends them to a file that does not contain what they came for. It is the same class of doc drift that `check_doc_counts.py`, `check_limitations_sync.py` and `check_examples_run.py` already exist to prevent elsewhere — an uncovered gap in an otherwise well-gated area rather than a novel problem.
## Suggested fix
1. Correct the two rows.
2. Extend `check_examples_readme.py` to parse backticked builtin names out of the Demonstrates column and assert each appears in the referenced source file (the column already backticks most entries; prose descriptions stay unchecked).
Option 2 is the load-bearing part; without it the rows will drift again.
Found while surveying `examples/` for #143. Verified against `ab23d7cc`.
0 条评论