update documentation for reject_federated_spam_event

Signed-off-by: jesopo <[email protected]>

Author: jesopo

docs/modules/spam_checker_callbacks.md

@@ -249,6 +249,23 @@ callback returns `False`, Synapse falls through to the next one. The value of th
 callback that does not return `False` will be used. If this happens, Synapse will not call
 any of the subsequent implementations of this callback.
 
+### `reject_federated_spam_event`
+
+_First introduced in Synapse v1.?.?_
+
+```python
+async def reject_federated_spam_event(event: "synapse.events.EventBase") -> bool
+```
+
+Called when checking whether a remote server can federate an event with us. **Returning
+`True` from this function will split-brain our view of a room's DAG, and thus you
+shouldn't use this callback unless you know what you are doing.**
+
+If multiple modules implement this callback, they will be considered in order. If a
+callback returns `False`, Synapse falls through to the next one. The value of the first
+callback that does not return `False` will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
+
 ## Example
 
 The example below is a module that implements the spam checker callback

docs/spam_checker.md

@@ -32,6 +32,7 @@ well as some specific methods:
 * `check_username_for_spam`
 * `check_registration_for_spam`
 * `check_media_file_for_spam`
+* `reject_federated_spam_event`
 
 The details of each of these methods (as well as their inputs and outputs)
 are documented in the `synapse.events.spamcheck.SpamChecker` class.
@@ -86,6 +87,10 @@ class ExampleSpamChecker:
 
     async def check_media_file_for_spam(self, file_wrapper, file_info):
         return False  # allow all media
+
+
+    async def reject_federated_spam_event(self, foo):
+        return False  # don't hard-reject any federated events
 ```
 
 ## Configuration