From 93909c30f183d677da37bef14f63e2298f97376a Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Wed, 12 May 2021 12:41:33 -0400
Subject: [PATCH 1/3] Clarify comments.

---
 synapse/handlers/space_summary.py | 50 ++++++++++++++++++++++++++++---
 1 file changed, 46 insertions(+), 4 deletions(-)

diff --git a/synapse/handlers/space_summary.py b/synapse/handlers/space_summary.py
index e35d91832b42..47ba95137c04 100644
--- a/synapse/handlers/space_summary.py
+++ b/synapse/handlers/space_summary.py
@@ -231,11 +231,15 @@ async def _summarize_local_room(
         Generate a room entry and a list of event entries for a given room.
 
         Args:
-            requester: The requesting user, or None if this is over federation.
+            requester:
+                The user requesting the summary, if it is a local request. None
+                if this is a federation request.
             room_id: The room ID to summarize.
             suggested_only: True if only suggested children should be returned.
                 Otherwise, all children are returned.
-            max_children: The maximum number of children to return for this node.
+            max_children:
+                The maximum number of children rooms to include. This is capped
+                to a server-set limit.
 
         Returns:
             A tuple of:
@@ -278,6 +282,26 @@ async def _summarize_remote_room(
         max_children: Optional[int],
         exclude_rooms: Iterable[str],
     ) -> Tuple[Sequence[JsonDict], Sequence[JsonDict]]:
+        """
+        Request room entries and a list of event entries for a given room by querying a remote server.
+
+        Args:
+            room: The room to summarize.
+            suggested_only: True if only suggested children should be returned.
+                Otherwise, all children are returned.
+            max_children:
+                The maximum number of children rooms to include. This is capped
+                to a server-set limit.
+            exclude_rooms:
+                Rooms IDs which do not need to be summarized.
+
+        Returns:
+            A tuple of:
+                An iterable of rooms.
+
+                An iterable of the sorted children events. This may be limited
+                to a maximum size or may include all children.
+        """
         room_id = room.room_id
         logger.info("Requesting summary for %s via %s", room_id, room.via)
 
@@ -310,8 +334,26 @@ async def _summarize_remote_room(
         )
 
     async def _is_room_accessible(self, room_id: str, requester: Optional[str]) -> bool:
-        # if we have an authenticated requesting user, first check if they are in the
-        # room
+        """
+        Calculate whether the room should be shown in the spaces summary.
+
+        It should be included if:
+
+        * The requester is joined or invited to the room.
+        * The history visibility is set to world readable.
+
+        Args:
+            room_id: The room ID to summarize.
+            requester:
+                The user requesting the summary, if it is a local request. None
+                if this is a federation request.
+
+        Returns:
+             True if the room should be included in the spaces summary.
+        """
+
+        # if we have an authenticated requesting user, first check if they are able to view
+        # stripped state in the room.
         if requester:
             try:
                 await self._auth.check_user_in_room(room_id, requester)

From 039f130968de3af1207e8d3f656f2553c08c19cf Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Wed, 12 May 2021 13:05:18 -0400
Subject: [PATCH 2/3] Remove a todo comment.

---
 synapse/handlers/space_summary.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/synapse/handlers/space_summary.py b/synapse/handlers/space_summary.py
index 47ba95137c04..953356f34d90 100644
--- a/synapse/handlers/space_summary.py
+++ b/synapse/handlers/space_summary.py
@@ -32,7 +32,6 @@
 logger = logging.getLogger(__name__)
 
 # number of rooms to return. We'll stop once we hit this limit.
-# TODO: allow clients to reduce this with a request param.
 MAX_ROOMS = 50
 
 # max number of events to return per room.

From 86fffaf95a8b8ed18f9af2cee60eef5a8e2d07f3 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Wed, 12 May 2021 13:06:41 -0400
Subject: [PATCH 3/3] Newsfragment

---
 changelog.d/9974.misc | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 changelog.d/9974.misc

diff --git a/changelog.d/9974.misc b/changelog.d/9974.misc
new file mode 100644
index 000000000000..9ddee2618e21
--- /dev/null
+++ b/changelog.d/9974.misc
@@ -0,0 +1 @@
+Update comments in the space summary handler.