--- 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). 
 #
 ##################################################################