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.

2 files changed, 6 insertions, 3 deletions

diff --git a/changelog.d/16950.misc b/changelog.d/16950.misc
new file mode 100644
index 0000000000..c5a0741c3b
--- /dev/null
+++ b/changelog.d/16950.misc
@@ -0,0 +1 @@
+Clarify docs for some room state functions.
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