Clarify presence router docs. (#16529)

2 files changed, 12 insertions, 3 deletions

diff --git a/changelog.d/16529.doc b/changelog.d/16529.doc
new file mode 100644

index 0000000000..0f8a87f293
--- /dev/null
+++ b/changelog.d/16529.doc
@@ -0,0 +1 @@
+Improve documentation of presence router.
diff --git a/docs/modules/presence_router_callbacks.md b/docs/modules/presence_router_callbacks.md

index d3da25cef4..b210f0e3cd 100644
--- a/docs/modules/presence_router_callbacks.md
+++ b/docs/modules/presence_router_callbacks.md
@@ -1,8 +1,16 @@
 # Presence router callbacks
 
-Presence router callbacks allow module developers to specify additional users (local or remote)
-to receive certain presence updates from local users. Presence router callbacks can be 
-registered using the module API's `register_presence_router_callbacks` method.
+Presence router callbacks allow module developers to define additional users
+which receive presence updates from local users. The additional users
+can be local or remote.
+
+For example, it could be used to direct all of `@alice:example.com` (a local user)'s
+presence updates to `@bob:matrix.org` (a remote user), even though they don't share a
+room. (Note that those presence updates might not make it to `@bob:matrix.org`'s client
+unless a similar presence router is running on that homeserver.)
+
+Presence router callbacks can be registered using the module API's
+`register_presence_router_callbacks` method.
 
 ## Callbacks