Comments and fixups

synapse/handlers/device.py

@@ -236,31 +236,47 @@ async def get_user_ids_changed(
 
         now_token = self._event_sources.get_current_token()
 
+        # We need to work out all the different membership changes for the user
+        # and user they share a room with, to pass to
+        # `generate_sync_entry_for_device_list`. See its docstring for details
+        # on the data required.
+
         joined_room_ids = await self.store.get_rooms_for_user(user_id)
 
+        # Get the set of rooms that the user has joined/left
         membership_changes = (
             await self.store.get_current_state_delta_membership_changes_for_user(
                 user_id, from_key=from_token.room_key, to_key=now_token.room_key
             )
         )
 
-        newly_joined_rooms = set()
-        newly_left_rooms = set()
+        # Check for newly joined or left rooms. We need to make sure that we add
+        # to newly joined in the case membership goes from join -> leave -> join
+        # again.
+        newly_joined_rooms: Set[str] = set()
+        newly_left_rooms: Set[str] = set()
         for change in membership_changes:
+            # We check for changes in "joinedness", i.e. if the membership has
+            # changed to or from JOIN.
             if change.membership == Membership.JOIN:
                 if change.prev_membership != Membership.JOIN:
                     newly_joined_rooms.add(change.room_id)
+                    newly_left_rooms.remove(change.room_id)
             elif change.prev_membership == Membership.JOIN:
+                newly_joined_rooms.remove(change.room_id)
                 newly_left_rooms.add(change.room_id)
 
-        newly_left_rooms -= newly_joined_rooms
-
-        # Then work out if any users have since joined
+        # We now work out if any other users have since joined or left the rooms
+        # the user is currently in. First we filter out rooms that we know
+        # haven't changed recently.
         rooms_changed = self.store.get_rooms_that_changed(
             joined_room_ids, from_token.room_key
         )
 
+        # List of membership changes per room
         room_to_deltas: Dict[str, List[StateDelta]] = {}
+        # The set of event IDs of membership events (so we can fetch their
+        # associated membership).
         memberships_to_fetch: Set[str] = set()
         for room_id in rooms_changed:
             # TODO: Only pull out membership events?
@@ -277,6 +293,7 @@ async def get_user_ids_changed(
                 if delta.prev_event_id:
                     memberships_to_fetch.add(delta.prev_event_id)
 
+        # Fetch all the memberships for the membership events
         event_id_to_memberships = await self.store.get_membership_from_event_ids(
             memberships_to_fetch
         )
@@ -287,13 +304,15 @@ async def get_user_ids_changed(
             Membership.KNOCK,
         )
 
-        newly_joined_or_invited_or_knocked_users = set()
-        newly_left_users = set()
+        # We now want to find any user that have newly joined/invited/knocked,
+        # or newly left, similarly to above.
+        newly_joined_or_invited_or_knocked_users: Set[str] = set()
+        newly_left_users: Set[str] = set()
         for _, deltas in room_to_deltas.items():
             for delta in deltas:
+                # Get the prev/new memberships for the delta
                 new_membership = None
                 prev_membership = None
-
                 if delta.event_id:
                     m = event_id_to_memberships.get(delta.event_id)
                     if m is not None:
@@ -303,14 +322,17 @@ async def get_user_ids_changed(
                     if m is not None:
                         prev_membership = m.membership
 
+                # Check if a user has newly joined/invited/knocked, or left.
                 if new_membership in joined_invited_knocked:
                     if prev_membership not in joined_invited_knocked:
                         newly_joined_or_invited_or_knocked_users.add(delta.state_key)
+                        newly_left_users.remove(delta.state_key)
                 elif prev_membership in joined_invited_knocked:
+                    newly_joined_or_invited_or_knocked_users.remove(delta.state_key)
                     newly_left_users.add(delta.state_key)
 
-        newly_left_users -= newly_joined_or_invited_or_knocked_users
-
+        # Now we actually calculate the device list entry with the information
+        # calculated above.
         device_list_updates = await self.generate_sync_entry_for_device_list(
             user_id=user_id,
             since_token=from_token,