From e5991af629df2e63c20c5f10e4589a9faf8305cb Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Mon, 13 Jul 2015 13:30:43 +0100
Subject: [PATCH] Comments

---
 synapse/handlers/receipts.py | 16 ++++++++++++----
 synapse/storage/receipts.py  | 11 +++++++++++
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/synapse/handlers/receipts.py b/synapse/handlers/receipts.py
index f847360d0..1925a4803 100644
--- a/synapse/handlers/receipts.py
+++ b/synapse/handlers/receipts.py
@@ -41,10 +41,9 @@ class ReceiptsHandler(BaseHandler):
     @defer.inlineCallbacks
     def received_client_receipt(self, room_id, receipt_type, user_id,
                                 event_id):
-        # 1. Persist.
-        # 2. Notify local clients
-        # 3. Notify remote servers
-
+        """Called when a client tells us a local user has read up to the given
+        event_id in the room.
+        """
         receipt = {
             "room_id": room_id,
             "receipt_type": receipt_type,
@@ -62,6 +61,8 @@ class ReceiptsHandler(BaseHandler):
 
     @defer.inlineCallbacks
     def _received_remote_receipt(self, origin, content):
+        """Called when we receive an EDU of type m.receipt from a remote HS.
+        """
         receipts = [
             {
                 "room_id": room_id,
@@ -79,6 +80,8 @@ class ReceiptsHandler(BaseHandler):
 
     @defer.inlineCallbacks
     def _handle_new_receipts(self, receipts):
+        """Takes a list of receipts, stores them and informs the notifier.
+        """
         for receipt in receipts:
             room_id = receipt["room_id"]
             receipt_type = receipt["receipt_type"]
@@ -105,6 +108,9 @@ class ReceiptsHandler(BaseHandler):
 
     @defer.inlineCallbacks
     def _push_remotes(self, receipts):
+        """Given a list of receipts, works out which remote servers should be
+        poked and pokes them.
+        """
         # TODO: Some of this stuff should be coallesced.
         for receipt in receipts:
             room_id = receipt["room_id"]
@@ -140,6 +146,8 @@ class ReceiptsHandler(BaseHandler):
 
     @defer.inlineCallbacks
     def get_receipts_for_room(self, room_id, to_key):
+        """Gets all receipts for a room, upto the given key.
+        """
         result = yield self.store.get_linearized_receipts_for_room(
             room_id, None, to_key
         )
diff --git a/synapse/storage/receipts.py b/synapse/storage/receipts.py
index 593032713..56b9fedfd 100644
--- a/synapse/storage/receipts.py
+++ b/synapse/storage/receipts.py
@@ -35,6 +35,8 @@ class ReceiptsStore(SQLBaseStore):
 
     @defer.inlineCallbacks
     def get_linearized_receipts_for_rooms(self, room_ids, from_key, to_key):
+        """Get receipts for multiple rooms for sending to clients.
+        """
         room_ids = set(room_ids)
 
         if from_key:
@@ -54,6 +56,8 @@ class ReceiptsStore(SQLBaseStore):
 
     @defer.inlineCallbacks
     def get_linearized_receipts_for_room(self, room_id, from_key, to_key):
+        """Get receipts for a single room for sending to clients.
+        """
         def f(txn):
             if from_key:
                 sql = (
@@ -107,6 +111,8 @@ class ReceiptsStore(SQLBaseStore):
     @cached
     @defer.inlineCallbacks
     def get_graph_receipts_for_room(self, room_id):
+        """Get receipts for sending to remote servers.
+        """
         rows = yield self._simple_select_list(
             table="receipts_graph",
             keyvalues={"room_id": room_id},
@@ -181,6 +187,11 @@ class ReceiptsStore(SQLBaseStore):
 
     @defer.inlineCallbacks
     def insert_receipt(self, room_id, receipt_type, user_id, event_ids, data):
+        """Insert a receipt, either from local client or remote server.
+
+        Automatically does conversion between linearized and graph
+        representations.
+        """
         if not event_ids:
             return