diff --git a/synapse/push/bulk_push_rule_evaluator.py b/synapse/push/bulk_push_rule_evaluator.py
index 1140788aa..bf4f1c583 100644
--- a/synapse/push/bulk_push_rule_evaluator.py
+++ b/synapse/push/bulk_push_rule_evaluator.py
@@ -189,6 +189,9 @@ class BulkPushRuleEvaluator(object):
                 if matches:
                     actions = [x for x in rule['actions'] if x != 'dont_notify']
                     if actions and 'notify' in actions:
+                        # Push rules say we should notify the user of this event,
+                        # so we mark it in the DB in the staging area. (This
+                        # will then get handled when we persist the event)
                         yield self.store.add_push_actions_to_staging(
                             event.event_id, uid, actions,
                         )
diff --git a/synapse/storage/event_push_actions.py b/synapse/storage/event_push_actions.py
index 28226455b..ea56d4d06 100644
--- a/synapse/storage/event_push_actions.py
+++ b/synapse/storage/event_push_actions.py
@@ -762,7 +762,8 @@ class EventPushActionsStore(SQLBaseStore):
         Args:
             event_id (str)
             user_id (str)
-            actions (list)
+            actions (list[dict|str]): An action can either be a string or
+                dict.
 
         Returns:
             Deferred
diff --git a/synapse/storage/schema/delta/47/push_actions_staging.sql b/synapse/storage/schema/delta/47/push_actions_staging.sql
index ec4b1d7d4..edccf4a96 100644
--- a/synapse/storage/schema/delta/47/push_actions_staging.sql
+++ b/synapse/storage/schema/delta/47/push_actions_staging.sql
@@ -13,6 +13,10 @@
  * limitations under the License.
  */
 
+-- Temporary staging area for push actions that have been calculated for an
+-- event, but the event hasn't yet been persisted.
+-- When the event is persisted the rows are moved over to the
+-- event_push_actions table.
 CREATE TABLE event_push_actions_staging (
     event_id TEXT NOT NULL,
     user_id TEXT NOT NULL,