Better explain the subtleties of module methods

docs/presence_routing_module.md

@@ -11,18 +11,18 @@ the running Synapse.
 
 The Python class is instantiated with two objects:
 
-* Some configuration object (see below).
+* A configuration object of some type (see below).
 * An instance of `synapse.module_api.ModuleApi`.
 
 It then implements methods related to presence routing.
 
 Note that one method of `ModuleApi` that may be useful is:
 
 ```python
-ModuleApi.send_local_online_presence_to(users: Iterable[str]) -> None
+async def ModuleApi.send_local_online_presence_to(users: Iterable[str]) -> None
 ```
 
-which can be given a list of local or remote MXIDs to broadcast local user
+which can be given a list of local or remote MXIDs to broadcast known, online user
 presence to (for those users that the receiving user is considered interested in). 
 It does not include state for users who are currently offline.
 
@@ -90,7 +90,7 @@ class ExamplePresenceRouter:
         state_updates: Iterable[UserPresenceState],
     ) -> Dict[str, Set[UserPresenceState]]:
         """Given an iterable of user presence updates, determine where each one
-        needs to go. Returned results will not impede presence updates that are
+        needs to go. Returned results will not affect presence updates that are
         sent between users who share a room.
 
         Args:
@@ -117,10 +117,10 @@ class ExamplePresenceRouter:
     async def get_interested_users(self, user_id: str) -> Union[Set[str], Literal["ALL"]]:
         """
         Retrieve a list of users that `user_id` is interested in receiving the
-        presence of, in addition to those it shares a room with.
+        presence of. This will be in addition to those they share a room with.
 
         Optionally, the literal str "ALL" can be returned to indicate that this user 
-        should receive all local and remote incoming presence updates.
+        should receive all incoming local and remote presence updates.
 
         Note that this method will only be called for local users.
 
@@ -137,16 +137,23 @@ class ExamplePresenceRouter:
         return set()
 ```
 
-#### A note on `get_interested_users`
+#### A note on `get_users_for_states` and `get_interested_users`
 
-`get_interested_users` is intended to filter out some presence updates early before
-they're passed to `get_users_for_states`. If `get_users_for_states` is implemented
-and `get_interested_users` is not, the default return value for
-`get_interested_users` is `"ALL"`. This is so that `get_users_for_states` is provided with
-all possible user presence updates, which it can then filter.
+Both of these methods are effectively two different sides of the same coin. The logic
+regarding which users should receive updates for other users should be the same 
+between them.
 
-If implementing `get_users_for_states`, mirroring the logic for which presence updates
-from one user should be sent to another will bring improved efficiency.
+`get_users_for_states` is called when presence updates come in from either federation 
+or local users, and is used to either direct local presence to remote users, or to
+wake up the sync streams of local users to collect remote presence.
+
+In contrast, `get_interested_users` is used to determine the users that presence should
+be fetched for when a local user is syncing. This presence in then retrieved, before
+being fed through `get_users_for_states` once again, with only the syncing user's
+routing information pulled from the resulting dictionary.
+
+Thus, if one method is implemented, the other should be as well. Their routing logic 
+should line up as well, else you may run into unintended behaviour.
 
 ## Configuration