--- a/mod_firewall/scripts/spam-blocking.pfw Fri Feb 24 16:41:48 2017 +0100
+++ b/mod_firewall/scripts/spam-blocking.pfw Fri Feb 24 15:58:37 2017 +0000
@@ -1,32 +1,47 @@
#### Anti-spam ruleset ###########################################
-# This script provides some foundational anti-spam
-# rules. It does not do any form of content filtering,
+#
+# This script provides some foundational anti-spam rules. It aims
+# to PASS stanzas that are definitely not spam, and DROP stanzas
+# that are very likely spam.
+#
+# It does not do any form of content filtering,
# but this can be implemented by other scripts and
-# modules as desired.
+# modules as desired using the chains documented below.
+#
#
# The following chains are available as extension
# points:
#
+# ::user/spam_check_custom
+# Apply additional rules to all stanzas before they are checked.
+# Mainly useful to PASS stanzas that you do not want to be
+# filtered.
+#
# ::user/spam_check_message_custom
-# Apply additional rules to messages from strangers
+# Apply additional rules to messages from strangers, aiming to
+# PASS stanzas that are not spam and jump to ::user/spam_reject
+# for stanzas that are considered spam.
#
# ::user/spam_check_message_content
-# Apply additional rules to messages that may be spam
+# Apply additional rules to messages that may be spam, based on
+# message content rules. These may contain more intensive rules,
+# so are executed after all other checks. Rules should jump to
+# ::user/spam_reject if a message is considered spam.
#
# ::user/spam_check_presence_custom
-# Apply additional rules to presence that may be spam
+# Apply additional rules to presence that may be spam.
#
# ::user/spam_check_subscription_request
-# Apply additional rules to subscription requests
+# Apply additional rules to subscription requests.
#
# ::user/spam_handle_unknown_custom
# Override default handling of stanzas that weren't explicitly
-# passed or rejected by the anti-spam checks
+# passed or rejected by the anti-spam checks.
#
# ::user/spam_reject_custom
# Override default handling of stanzas that have
# been recognised as spam (default is to bounce
-# a policy-violation error)
+# a policy-violation error).
#
##################################################################