From 39b4f10533fded08647c198c80e6b185bc8558e0 Mon Sep 17 00:00:00 2001
From: Eric Eastwood <eric.eastwood@beta.gouv.fr>
Date: Tue, 18 Jun 2024 19:55:12 -0500
Subject: [PATCH] Update comments

---
 synapse/handlers/sliding_sync.py | 14 +++++++++-----
 tests/rest/client/test_sync.py   |  2 +-
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/synapse/handlers/sliding_sync.py b/synapse/handlers/sliding_sync.py
index f2b29ce1d1..cb5274d495 100644
--- a/synapse/handlers/sliding_sync.py
+++ b/synapse/handlers/sliding_sync.py
@@ -756,10 +756,10 @@ class SlidingSyncHandler:
         # Assemble the list of timeline events
         timeline_events: List[EventBase] = []
         limited = False
-        # We want to use `to_token` (vs `from_token`) because we look backwards from the
-        # `to_token` up to the `timeline_limit` and we might not reach `from_token`
-        # before we hit the limit. We will update the room stream position once we've
-        # fetched the events.
+        # We want to start off using the `to_token` (vs `from_token`) because we look
+        # backwards from the `to_token` up to the `timeline_limit` and we might not
+        # reach the `from_token` before we hit the limit. We will update the room stream
+        # position once we've fetched the events.
         prev_batch_token = to_token
         if room_sync_config.timeline_limit > 0:
             newly_joined = False
@@ -803,6 +803,7 @@ class SlidingSyncHandler:
             # most recent).
             timeline_events.reverse()
 
+            # Make sure we don't expose any events that the client shouldn't see
             timeline_events = await filter_events_for_client(
                 self.storage_controllers,
                 user.to_string(),
@@ -851,11 +852,14 @@ class SlidingSyncHandler:
                         # this more with a binary search (bisect).
                         break
 
+            # Update the `prev_batch_token` to point to the position that allows us to
+            # keep paginating backwards from the oldest event we return in the timeline.
             prev_batch_token = prev_batch_token.copy_and_replace(
                 StreamKeyType.ROOM, new_room_key
             )
 
-        # Figure out any stripped state events for invite/knocks
+        # Figure out any stripped state events for invite/knocks. This allows the
+        # potential joiner to identify the room.
         stripped_state: List[JsonDict] = []
         if rooms_for_user_membership_at_to_token.membership in {
             Membership.INVITE,
diff --git a/tests/rest/client/test_sync.py b/tests/rest/client/test_sync.py
index d538716e5a..838ff6e2b4 100644
--- a/tests/rest/client/test_sync.py
+++ b/tests/rest/client/test_sync.py
@@ -1874,7 +1874,7 @@ class SlidingSyncTestCase(unittest.HomeserverTestCase):
             [],
             channel.json_body["rooms"][room_id1]["timeline"],
         )
-        # We should have some stripped state so the potential joiner can identify the
+        # We should have some `stripped_state` so the potential joiner can identify the
         # room (we don't care about the order).
         self.assertCountEqual(
             channel.json_body["rooms"][room_id1]["invite_state"],