ITADN

`examples/README.md`'s Demonstrates column has drifted and is not gated

#1351Openaallan 创建于 6 天前
documentationtesting
A
aallancommented
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 条评论