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.

changelog.d/16950.misc

@@ -0,0 +1 @@
+Clarify docs for some room state functions.

synapse/storage/controllers/state.py

@@ -273,8 +273,10 @@ async def get_state_ids_for_events(
         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 @@ async def get_state_ids_for_event(
         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