Clarify docs for some room state functions (#16950)

State *before* an event is different to state *after* that event, and
people tend to assume the wrong one.

1 files changed, 5 insertions, 3 deletions

diff --git a/synapse/storage/controllers/state.py b/synapse/storage/controllers/state.py
index 22d93a561c..f9eced23bf 100644
--- a/synapse/storage/controllers/state.py
+++ b/synapse/storage/controllers/state.py
@@ -273,8 +273,10 @@ class StateStorageController:
         await_full_state: bool = True,
     ) -> Dict[str, StateMap[str]]:
         """
-        Get the state dicts corresponding to a list of events, containing the event_ids
-        of the state events (as opposed to the events themselves)
+        Get the room states after each of a list of events.
+
+        For each event in `event_ids`, the result contains a map from state tuple
+        to the event_ids of the state event (as opposed to the events themselves).
 
         Args:
             event_ids: events whose state should be returned
@@ -347,7 +349,7 @@ class StateStorageController:
         await_full_state: bool = True,
     ) -> StateMap[str]:
         """
-        Get the state dict corresponding to a particular event
+        Get the state dict corresponding to the state after a particular event
 
         Args:
             event_id: event whose state should be returned