High-level document how the insertion->chunk lookup works

synapse/storage/databases/main/event_federation.py

@@ -1001,6 +1001,13 @@ def _get_backfill_events(self, txn, room_id, event_list, limit):
 
             event_results.add(event_id)
 
+            # Try and find any potential historical chunks of message history.
+            #
+            # First we look for an insertion event connected to the current
+            # event (by prev_event). If we find any, we need to go and try to
+            # find any chunk events connected to the insertion event (by
+            # chunk_id). If we find any, we'll add them to the queue and
+            # navigate up the DAG like normal in the next iteration of the loop.
             txn.execute(
                 connected_insertion_event_query, (event_id, limit - len(event_results))
             )
@@ -1028,6 +1035,7 @@ def _get_backfill_events(self, txn, room_id, event_list, limit):
                     if row[1] not in event_results:
                         queue.put((-row[0], row[1]))
 
+            # Navigate up the DAG by prev_event
             txn.execute(query, (event_id, False, limit - len(event_results)))
             prev_event_id_results = txn.fetchall()
             logger.debug(