From 0c0342b994db22514256494cf5acefc2d26f679a Mon Sep 17 00:00:00 2001
From: Ivan Enderlin <ivan@mnt.io>
Date: Mon, 25 Mar 2024 14:51:53 +0100
Subject: [PATCH] doc(sdk): Add doc for `assert_items_eq!`.

---
 crates/matrix-sdk/src/event_cache/linked_chunk.rs | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/crates/matrix-sdk/src/event_cache/linked_chunk.rs b/crates/matrix-sdk/src/event_cache/linked_chunk.rs
index 31b11497e..315cabb53 100644
--- a/crates/matrix-sdk/src/event_cache/linked_chunk.rs
+++ b/crates/matrix-sdk/src/event_cache/linked_chunk.rs
@@ -975,6 +975,18 @@ mod tests {
         LinkedChunkError, Position,
     };
 
+    /// A macro to test the items and the gap of a `LinkedChunk`.
+    /// A chunk is delimited by `[` and `]`. An item chunk has the form `[a, b,
+    /// c]` where `a`, `b` and `c` are items. A gap chunk has the form `[-]`.
+    ///
+    /// For example, here is an assertion of 7 chunks: 1 items chunk, 1 gap
+    /// chunk, 2 items chunks, 1 gap chunk, 2 items chunk. `a` is the oldest
+    /// item of the oldest chunk (the first chunk), and `i` is the oldest (and
+    /// newest) item of the newest chunk (the last chunk).
+    ///
+    /// ```rust,no_run
+    /// assert_items_eq!(linked_chunk, ['a'] [-] ['b', 'c', 'd'] ['e'] [-] ['f', 'g', 'h'] ['i']);
+    /// ```
     macro_rules! assert_items_eq {
         ( @_ [ $iterator:ident ] { [-] $( $rest:tt )* } { $( $accumulator:tt )* } ) => {
             assert_items_eq!(