[PATCH] rust: rbtree: document peek_next() on the immutable cursor

[Juan Patricio Marchetto]

The immutable Cursor has a single example, covering cursor_front() and
current(). Its peek_next() has none: the only worked example of peeking
belongs to CursorMut.

That leaves the most common reason to hold an immutable cursor
undocumented. cursor_lower_bound() stops on an exact match, so a caller
looking for the first key strictly greater than the one it supplied has
to peek past it. Getting that wrong yields the key the caller already
has, which for an iterating caller means no forward progress at all.

Document the idiom, including the case where the looked-up key is the
largest in the tree and therefore has no successor.

Assisted-by: Claude:claude-opus-5
Signed-off-by: Juan Patricio Marchetto <juanpatriciomarchetto@xxxxxxxxx>
---
 rust/kernel/rbtree.rs | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/rust/kernel/rbtree.rs b/rust/kernel/rbtree.rs
index 6fbd579d4a4..2a0379374e2 100644
--- a/rust/kernel/rbtree.rs
+++ b/rust/kernel/rbtree.rs
@@ -811,6 +811,32 @@ pub struct CursorMut<'a, K, V> {
 ///
 /// # Ok::<(), Error>(())
 /// ```
+///
+/// [`Cursor::peek_next`] steps past a key that matched exactly, which is how a caller
+/// reaches the first key strictly greater than the one it looked up.
+///
+/// ```
+/// use kernel::{alloc::flags, rbtree::RBTree};
+///
+/// // Create a new tree.
+/// let mut tree = RBTree::new();
+///
+/// // Insert three elements.
+/// tree.try_create_and_insert(10, 100, flags::GFP_KERNEL)?;
+/// tree.try_create_and_insert(20, 200, flags::GFP_KERNEL)?;
+/// tree.try_create_and_insert(30, 300, flags::GFP_KERNEL)?;
+///
+/// // `cursor_lower_bound` stops on the exact match, so the successor is one peek away.
+/// let cursor = tree.cursor_lower_bound(&20).unwrap();
+/// assert_eq!(cursor.current(), (&20, &200));
+/// assert_eq!(cursor.peek_next().unwrap(), (&30, &300));
+///
+/// // The largest key has no successor.
+/// let cursor = tree.cursor_lower_bound(&30).unwrap();
+/// assert!(cursor.peek_next().is_none());
+///
+/// # Ok::<(), Error>(())
+/// ```
 pub struct Cursor<'a, K, V> {
     _tree: PhantomData<&'a RBTree<K, V>>,
     current: NonNull<bindings::rb_node>,
-- 
2.43.0