Clarifications to the push module (#2634)

* Minor clarifications to the push spec
* move conditions before defaults

changelogs/client_server/newsfragments/2634.clarification

@@ -0,0 +1 @@
+Minor clarifications to the "Push Notifications" module.

specification/modules/push.rst

@@ -33,13 +33,13 @@ Push Notifications
     Matrix   |                     |                    |  |      |            |
  Client/Server API  +              |                    |  |      |            |
              |      |              +--------------------+  +-------------------+
-             |   +--+-+                                           |             
+             |   +--+-+                                           |
-             |   |    <-------------------------------------------+             
+             |   |    <-------------------------------------------+
-             +---+    |                                                        
+             +---+    |
-                 |    |          Provider Push Protocol                        
+                 |    |          Provider Push Protocol
-                 +----+                                                        
+                 +----+
-                                                                               
+
-         Mobile Device or Client                                               
+         Mobile Device or Client
 
 
 This module adds support for push notifications. Homeservers send notifications
@@ -135,8 +135,9 @@ There are different "kinds" of push rules and each rule has an associated
 priority. Every push rule MUST have a ``kind`` and ``rule_id``. The ``rule_id``
 is a unique string within the kind of rule and its' scope: ``rule_ids`` do not
 need to be unique between rules of the same kind on different devices. Rules may
-have extra keys depending on the value of ``kind``. The different kinds of rule
+have extra keys depending on the value of ``kind``.
-in descending order of priority are:
+
+The different ``kind``\ s of rule, in the order that they are checked, are:
 
 Override Rules ``override``
   The highest priority rules are user-configured overrides.
@@ -156,15 +157,6 @@ Underride rules ``underride``
   These are identical to ``override`` rules, but have a lower priority than
   ``content``, ``room`` and ``sender`` rules.
 
-This means that the full list of rule kinds, in descending priority order, is
-as follows:
-
-* Global Override
-* Global Content
-* Global Room
-* Global Sender
-* Global Underride
-
 Rules with the same ``kind`` can specify an ordering priority. This determines
 which rule is selected in the event of multiple matches. For example, a rule
 matching "tea" and a separate rule matching "time" would both match the sentence
@@ -224,6 +216,55 @@ Tweaks are passed transparently through the homeserver so client applications
 and Push Gateways may agree on additional tweaks. For example, a tweak may be
 added to specify how to flash the notification light on a mobile device.
 
+Conditions
+++++++++++
+
+``override`` and ``underride`` rules MAY have a list of 'conditions'.
+All conditions must hold true for an event in order for the rule to match.
+A rule with no conditions always matches. The following conditions are defined:
+
+``event_match``
+  This is a glob pattern match on a field of the event. Parameters:
+
+  * ``key``: The dot-separated field of the event to match, e.g. ``content.body``
+  * ``pattern``: The glob-style pattern to match against. Patterns with no
+    special glob characters should be treated as having asterisks
+    prepended and appended when testing the condition.
+
+``contains_display_name``
+  This matches unencrypted messages where ``content.body`` contains the owner's
+  display name in that room. This is a separate rule because display names may
+  change and as such it would be hard to maintain a rule that matched the user's
+  display name. This condition has no parameters.
+
+``room_member_count``
+  This matches the current number of members in the room. Parameters:
+
+  * ``is``: A decimal integer optionally prefixed by one of, ``==``, ``<``,
+    ``>``, ``>=`` or ``<=``. A prefix of ``<`` matches rooms where the member
+    count is strictly less than the given number and so forth. If no prefix is
+    present, this parameter defaults to ``==``.
+
+``sender_notification_permission``
+  This takes into account the current power levels in the room, ensuring the
+  sender of the event has high enough power to trigger the notification.
+
+  Parameters:
+
+  * ``key``: A string that determines the power level the sender must have to trigger
+    notifications of a given type, such as ``room``. Refer to the `m.room.power_levels`_
+    event schema for information about what the defaults are and how to interpret the event.
+    The ``key`` is used to look up the power level required to send a notification type
+    from the ``notifications`` object in the power level event content.
+
+Unrecognised conditions MUST NOT match any events, effectively making the push
+rule disabled.
+
+``room``, ``sender`` and ``content`` rules do not have conditions in the same
+way, but instead have predefined conditions. In the cases of ``room`` and
+``sender`` rules, the ``rule_id`` of the rule determines its behaviour.
+
+
 Predefined Rules
 ++++++++++++++++
 Homeservers can specify "server-default rules" which operate at a lower priority
@@ -237,7 +278,7 @@ Default Override Rules
 
 ``.m.rule.master``
 ``````````````````
-Matches all events, this can be enabled to turn off all push notifications
+Matches all events. This can be enabled to turn off all push notifications
 other than those generated by override rules set by the user. By default this
 rule is disabled.
 
@@ -257,9 +298,7 @@ Definition
 
 ``.m.rule.suppress_notices``
 ````````````````````````````
-Matches messages with a ``msgtype`` of ``notice``. This should be an
+Matches messages with a ``msgtype`` of ``notice``.
-``override`` rule so that it takes priority over ``content`` / ``sender`` /
-``room`` rules.
 
 Definition:
 
@@ -650,55 +689,6 @@ Definition:
         ]
    }
 
-
-Conditions
-++++++++++
-
-Override, Underride and Default Rules MAY have a list of 'conditions'.
-All conditions must hold true for an event in order to apply the ``action`` for
-the event. A rule with no conditions always matches. Room, Sender, User and
-Content rules do not have conditions in the same way, but instead have
-predefined conditions. These conditions can be configured using the parameters
-outlined below. In the cases of room and sender rules, the ``rule_id`` of the
-rule determines its behaviour. The following conditions are defined:
-
-``event_match``
-  This is a glob pattern match on a field of the event. Parameters:
-
-  * ``key``: The dot-separated field of the event to match, e.g. ``content.body``
-  * ``pattern``: The glob-style pattern to match against. Patterns with no
-    special glob characters should be treated as having asterisks
-    prepended and appended when testing the condition.
-
-``contains_display_name``
-  This matches unencrypted messages where ``content.body`` contains the owner's
-  display name in that room. This is a separate rule because display names may
-  change and as such it would be hard to maintain a rule that matched the user's
-  display name. This condition has no parameters.
-
-``room_member_count``
-  This matches the current number of members in the room. Parameters:
-
-  * ``is``: A decimal integer optionally prefixed by one of, ``==``, ``<``,
-    ``>``, ``>=`` or ``<=``. A prefix of ``<`` matches rooms where the member
-    count is strictly less than the given number and so forth. If no prefix is
-    present, this parameter defaults to ``==``.
-
-``sender_notification_permission``
-  This takes into account the current power levels in the room, ensuring the
-  sender of the event has high enough power to trigger the notification.
-
-  Parameters:
-
-  * ``key``: A string that determines the power level the sender must have to trigger
-    notifications of a given type, such as ``room``. Refer to the `m.room.power_levels`_
-    event schema for information about what the defaults are and how to interpret the event.
-    The ``key`` is used to look up the power level required to send a notification type
-    from the ``notifications`` object in the power level event content.
-
-Unrecognised conditions MUST NOT match any events, effectively making the push
-rule disabled.
-
 Push Rules: API
 ~~~~~~~~~~~~~~~