From 5eb1837b0beb0e7530318f2364e142515023fe20 Mon Sep 17 00:00:00 2001
From: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
Date: Wed, 7 Oct 2026 06:37:36 +0700
Subject: [PATCH] docs: ScreenDiff's changed_rows and style_changes get
 runnable examples

`changed_rows` gave its example as code inside a sentence, which nothing
compiles, and `style_changes` had none. Both now share one doctest scene,
the one the prose describes: a reverse-video highlight moving from row 1
to row 2 of a parsed three-row menu. `changed_rows` asserts `[1, 2]`, and
`style_changes` asserts the two `(row, before, after)` tuples, `(1,
"0-5 reverse", "(none)")` and `(2, "(none)", "0-5 reverse")`.

The screens come from `Screen::parse`, so neither doctest needs a terminal
and both run on every platform. Each fails when its expected value is
changed, checked by editing it; they pass with default, no default and all
features, and rustdoc is clean with `-D warnings`.

Closes #542

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
---
 crates/termlens/src/screen/diff.rs | 38 +++++++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/crates/termlens/src/screen/diff.rs b/crates/termlens/src/screen/diff.rs
index 75eaa3d..9d75563 100644
--- a/crates/termlens/src/screen/diff.rs
+++ b/crates/termlens/src/screen/diff.rs
@@ -183,8 +183,22 @@ impl ScreenDiff {
 
     /// The rows with at least one changed cell, ascending, each once —
     /// so "the highlight moved from row 1 to row 2 and nothing else
-    /// changed" is `assert_eq!(diff.changed_rows().collect::<Vec<_>>(),
-    /// [1, 2])` rather than a dedup over [`cells`](Self::cells).
+    /// changed" is one assertion rather than a dedup over
+    /// [`cells`](Self::cells):
+    ///
+    /// ```
+    /// # fn main() -> termlens::Result<()> {
+    /// use termlens::Screen;
+    ///
+    /// let menu = "size: 10x3  cursor: 0,0\nitem a\nitem b\nitem c\n\nstyles:\n";
+    /// let before = Screen::parse(&format!("{menu}1: 0-5 reverse"))?;
+    /// let after = Screen::parse(&format!("{menu}2: 0-5 reverse"))?;
+    ///
+    /// let diff = before.diff(&after);
+    /// assert_eq!(diff.changed_rows().collect::<Vec<_>>(), [1, 2]);
+    /// # Ok(())
+    /// # }
+    /// ```
     ///
     /// Within the overlap of the two grids, like `cells`; a size or cursor
     /// change alone leaves this empty while [`is_empty`](Self::is_empty)
@@ -198,7 +212,25 @@ impl ScreenDiff {
     /// writes (`(none)` for an all-default row), ascending by row. A row
     /// whose text changed under unchanged styles is not listed; a row
     /// whose styles changed under unchanged text is, since a changed
-    /// style is a changed cell.
+    /// style is a changed cell. The highlight from
+    /// [`changed_rows`](Self::changed_rows) again, row by row:
+    ///
+    /// ```
+    /// # fn main() -> termlens::Result<()> {
+    /// use termlens::Screen;
+    ///
+    /// let menu = "size: 10x3  cursor: 0,0\nitem a\nitem b\nitem c\n\nstyles:\n";
+    /// let before = Screen::parse(&format!("{menu}1: 0-5 reverse"))?;
+    /// let after = Screen::parse(&format!("{menu}2: 0-5 reverse"))?;
+    ///
+    /// let diff = before.diff(&after);
+    /// assert_eq!(
+    ///     diff.style_changes().collect::<Vec<_>>(),
+    ///     [(1, "0-5 reverse", "(none)"), (2, "(none)", "0-5 reverse")]
+    /// );
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn style_changes(&self) -> impl Iterator<Item = (u16, &str, &str)> {
         self.style_changes
             .iter()