diff --git a/synapse/api/filtering.py b/synapse/api/filtering.py
index 63d5c75f43..6cadb5645d 100644
--- a/synapse/api/filtering.py
+++ b/synapse/api/filtering.py
@@ -254,6 +254,9 @@ class Filter(object):
         Returns:
             bool: True if the event matches
         """
+        # We usually get the full "events" as dictionaries coming through,
+        # except for presence which actually gets passed around as its own
+        # namedtuple type.
         if isinstance(event, UserPresenceState):
             sender = event.user_id
             room_id = None
diff --git a/synapse/handlers/presence.py b/synapse/handlers/presence.py
index 46704c62a0..f714bcb53d 100644
--- a/synapse/handlers/presence.py
+++ b/synapse/handlers/presence.py
@@ -984,6 +984,9 @@ def should_notify(old_state, new_state):
 def format_user_presence_state(state, now, include_user_id=True):
     """Convert UserPresenceState to a format that can be sent down to clients
     and to other servers.
+
+    The "user_id" is optional so that this function can be used to format presence
+    updates for client /sync responses and for federation /send requests.
     """
     content = {
         "presence": state.state,