Add some comments

1 files changed, 12 insertions, 3 deletions

diff --git a/synapse/handlers/federation.py b/synapse/handlers/federation.py
index 310db3fb46..1296e22af6 100644
--- a/synapse/handlers/federation.py
+++ b/synapse/handlers/federation.py
@@ -542,9 +542,16 @@ class FederationHandler(BaseHandler):
     def backfill(self, dest, room_id, limit, extremities):
         """ Trigger a backfill request to `dest` for the given `room_id`
 
-        This will attempt to get more events from the remote. This may return
-        be successfull and still return no events if the other side has no new
-        events to offer.
+        This will attempt to get more events from the remote. If the other side
+        has no new events to offer, this will return an empty list.
+
+        As the events are received, we check their signatures, and also do some
+        sanity-checking on them. If any of the backfilled events are invalid,
+        this method throws a SynapseError.
+
+        TODO: make this more useful to distinguish failures of the remote
+        server from invalid events (there is probably no point in trying to
+        re-fetch invalid events from every other HS in the room.)
         """
         if dest == self.server_name:
             raise SynapseError(400, "Can't backfill from self.")
@@ -556,6 +563,8 @@ class FederationHandler(BaseHandler):
             extremities=extremities,
         )
 
+        # do some sanity-checking of the received events, before we go and
+        # do state resolution across 1000 events.
         for ev in events:
             self._sanity_check_event(ev)