Skip to content

docs: a review pass, fifteen claims the code contradicts - #562

Merged
vyncint merged 1 commit into
mainfrom
docs/review-0.11.5
Oct 7, 2026
Merged

vyncint merged 1 commit into
mainfrom
docs/review-0.11.5

Conversation

@vyncint

@vyncint vyncint commented Oct 7, 2026 •

Copy link
Copy Markdown
Owner

Each was checked against the code or by running it before it changed;
one more item is a style tidy, marked as such.

README:

  • Screen::parse reads the snapshot format, not an insta .snap: it
    rejects the --- header on line 1. The body below it parses, and the
    termlens command reads a whole .snap because it strips the header.
  • The skill has five recipes, not four.

SKILL.md:

  • §7's mask row said mask_matching "spans a wrap the way find_all
    does". A value split by a soft wrap is two rows and stays unmasked
    (measured: 10 columns, SECRET-VALUE-42); a needle with \n is what
    spans rows. Rule 12 already says so for contains.
  • Rule 10 said format!("{:?}") is the same as Display. It wraps the
    text in Screen(…), which Screen::parse, diff and render refuse.
  • §6 said every error's Display ends with the screen. Only the wait
    errors (timeout, EOF, emulator) and a failed write carry one.

SECURITY.md: "bot-authored commits are rejected by CI" is true except for
Dependabot, which CONTRIBUTING's AI tooling policy exempts from the
identity rule only; the provenance line now says so.

DESIGN.md:

  • The writer queue is unbounded (mpsc::channel), capped on reply bytes;
    one paragraph said bounded, the next unbounded.
  • The user-facing Windows list is in docs/LIMITATIONS.md, not the README.
  • CSI 18 t is answered, and 14 t/16 t once a cell size is declared,
    so "the non-pixel CSI t reports" were never all unanswered; the same
    correction in LIMITATIONS.md names 11 t and 19 t instead.
  • The compatibility corpus starts at 0.10.1, not "each published release".

emit's steps: an argument beginning with -- must be a step, so emit --foo exits 2 rather than printing --foo; TEXT and --text say so.

Rustdoc:

  • Unsupported's summary was Clipboard's first sentence, so docs.rs
    described the type as clipboard data; the sentence is back on
    Clipboard, which had no summary.
  • assert_screen_snapshot! repeated the Display-versus-Debug reason that
    docs(skill): rule 9 gives the true reason, and §6 reads the Debug form too #559 corrected in the skill.
  • wait_frame pointed at a README Windows note that is not in the README.
  • Screen's Debug impl said "exactly like Display"; it adds Screen(…).
  • Style, not a contradiction: mask_matching carried the crate's only
    # Examples heading; the rest of the crate's doctests have none.

Found by a documentation sweep; the same sweep found the relative
current_dir bug and the inspect help errors fixed in #561.

Each was checked against the code or by running it before it changed;
one more item is a style tidy, marked as such.

README:
- `Screen::parse` reads the snapshot format, not an insta `.snap`: it
  rejects the `---` header on line 1. The body below it parses, and the
  `termlens` command reads a whole `.snap` because it strips the header.
- The skill has five recipes, not four.

SKILL.md:
- §7's mask row said `mask_matching` "spans a wrap the way `find_all`
  does". A value split by a soft wrap is two rows and stays unmasked
  (measured: 10 columns, `SECRET-VALUE-42`); a needle with `\n` is what
  spans rows. Rule 12 already says so for `contains`.
- Rule 10 said `format!("{:?}")` is the same as `Display`. It wraps the
  text in `Screen(…)`, which `Screen::parse`, `diff` and `render` refuse.
- §6 said every error's `Display` ends with the screen. Only the wait
  errors (timeout, EOF, emulator) and a failed write carry one.

SECURITY.md: "bot-authored commits are rejected by CI" is true except for
Dependabot, which CONTRIBUTING's AI tooling policy exempts from the
identity rule only; the provenance line now says so.

DESIGN.md:
- The writer queue is unbounded (`mpsc::channel`), capped on reply bytes;
  one paragraph said bounded, the next unbounded.
- The user-facing Windows list is in docs/LIMITATIONS.md, not the README.
- `CSI 18 t` is answered, and `14 t`/`16 t` once a cell size is declared,
  so "the non-pixel `CSI t` reports" were never all unanswered; the same
  correction in LIMITATIONS.md names `11 t` and `19 t` instead.
- The compatibility corpus starts at 0.10.1, not "each published release".

emit's steps: an argument beginning with `--` must be a step, so `emit
--foo` exits 2 rather than printing `--foo`; TEXT and `--text` say so.

Rustdoc:
- `Unsupported`'s summary was `Clipboard`'s first sentence, so docs.rs
  described the type as clipboard data; the sentence is back on
  `Clipboard`, which had no summary.
- `assert_screen_snapshot!` repeated the Display-versus-Debug reason that
  #559 corrected in the skill.
- `wait_frame` pointed at a README Windows note that is not in the README.
- `Screen`'s Debug impl said "exactly like Display"; it adds `Screen(…)`.
- Style, not a contradiction: `mask_matching` carried the crate's only
  `# Examples` heading; the rest of the crate's doctests have none.

Found by a documentation sweep; the same sweep found the relative
`current_dir` bug and the inspect help errors fixed in #561.

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
@vyncint
vyncint force-pushed the docs/review-0.11.5 branch from c046ea0 to 0b794e0 Compare October 7, 2026 00:03
@vyncint vyncint changed the title docs: a review pass, thirteen claims the code contradicts docs: a review pass, fifteen claims the code contradicts Oct 7, 2026
@vyncint
vyncint merged commit a9edfe7 into main Oct 7, 2026
16 checks passed
@vyncint
vyncint deleted the docs/review-0.11.5 branch October 7, 2026 00:19
@vyncint vyncint mentioned this pull request Oct 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant