Clean up the pushrules API doc

* make it clearer which fields go in which parts of the rule
* the example given appeared to be for a content rule, so use a content rule
  consistently through the examples.

api/client-server/definitions/push_condition.yaml

@@ -11,6 +11,9 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+
+title: PushCondition
+type: object
 properties:
   kind:
     enum:
@@ -18,4 +21,25 @@ properties:
     - contains_display_name
     - room_member_count
     type: string
-type: object
+  key:
+    type: string
+    description: |-
+      Required for ``event_match`` conditions. The dot-separated field of the
+      event to match.
+    x-example: content.body
+  pattern:
+    type: string
+    description: |-
+      Required for ``event_match`` conditions. 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.
+  is:
+    type: string
+    description: |-
+      Required for ``room_member_count`` conditions. 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 ==.
+required:
+  - kind

api/client-server/definitions/push_rule.yaml

@@ -11,6 +11,9 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+
+title: PushRule
+type: object
 properties:
   actions:
     items:
@@ -18,11 +21,36 @@ properties:
       - object
       - string
     type: array
+    description: |-
+      The actions to perform when this rule is matched.
   default:
     type: boolean
+    description: |-
+      Whether this is a default rule, or has been set explicitly.
   enabled:
     type: boolean
+    description: |-
+      Whether the push rule is enabled or not.
   rule_id:
     type: string
-title: PushRule
+    description: |-
-type: object
+      The ID of this rule.
+  conditions:
+    type: array
+    items:
+      allOf:
+      - $ref: push_condition.yaml
+    description: |-
+      The conditions that must hold true for an event in order for a rule to be
+      applied to an event. A rule with no conditions always matches. Only
+      applicable to ``underride`` and ``override`` rules.
+  pattern:
+    type: string
+    description: |-
+      The glob-style pattern to match against.  Only applicable to ``content``
+      rules.
+required:
+  - actions
+  - default
+  - enabled
+  - rule_id

api/client-server/pushrules.yaml

@@ -262,7 +262,7 @@ paths:
           type: string
           name: kind
           required: true
-          x-example: room
+          x-example: content
           enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
@@ -270,7 +270,7 @@ paths:
           type: string
           name: ruleId
           required: true
-          x-example: "#spam:example.com"
+          x-example: "nocake"
           description: |
             The identifier for the rule.
       responses:
@@ -284,13 +284,13 @@ paths:
                 "actions": [
                     "dont_notify"
                 ],
-                "rule_id": "#spam:matrix.org",
+                "pattern": "cake*lie",
+                "rule_id": "nocake",
                 "enabled": true
               }
           schema:
             type: object
             description: The push rule.
-            title: PushRule
             allOf: [
               "$ref": "definitions/push_rule.yaml"
             ]
@@ -314,7 +314,7 @@ paths:
           type: string
           name: kind
           required: true
-          x-example: room
+          x-example: content
           enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
@@ -322,7 +322,7 @@ paths:
           type: string
           name: ruleId
           required: true
-          x-example: "#spam:example.com"
+          x-example: "nocake"
           description: |
             The identifier for the rule.
       responses:
@@ -355,7 +355,7 @@ paths:
           type: string
           name: kind
           required: true
-          x-example: room
+          x-example: content
           enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
@@ -363,7 +363,7 @@ paths:
           type: string
           name: ruleId
           required: true
-          x-example: "#spam:example.com"
+          x-example: "nocake"
           description: |
             The identifier for the rule.
         - in: query
@@ -411,11 +411,14 @@ paths:
                 description: |-
                   The conditions that must hold true for an event in order for a
                   rule to be applied to an event. A rule with no conditions
-                  always matches.
+                  always matches. Only applicable to ``underride`` and ``override`` rules.
                 items:
                   type: object
-                  title: conditions
                   allOf: [ "$ref": "definitions/push_condition.yaml" ]
+              pattern:
+                type: string
+                description: |-
+                  Only applicable to ``content`` rules. The glob-style pattern to match against.
             required: ["actions"]
       responses:
         200:
@@ -461,7 +464,7 @@ paths:
           type: string
           name: kind
           required: true
-          x-example: room
+          x-example: cake
           enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
@@ -469,7 +472,7 @@ paths:
           type: string
           name: ruleId
           required: true
-          x-example: "#spam:example.com"
+          x-example: nocake
           description: |
             The identifier for the rule.
       responses:
@@ -505,7 +508,7 @@ paths:
           type: string
           name: kind
           required: true
-          x-example: room
+          x-example: content
           enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
@@ -513,7 +516,7 @@ paths:
           type: string
           name: ruleId
           required: true
-          x-example: "#spam:example.com"
+          x-example: "nocake"
           description: |
             The identifier for the rule.
         - in: body
@@ -562,7 +565,7 @@ paths:
           type: string
           name: kind
           required: true
-          x-example: room
+          x-example: content
           enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
@@ -570,7 +573,7 @@ paths:
           type: string
           name: ruleId
           required: true
-          x-example: "#spam:example.com"
+          x-example: nocake
           description: |
             The identifier for the rule.
       responses:

changelogs/client_server.rst

@@ -7,6 +7,8 @@
     (`#362 <https://github.com/matrix-org/matrix-doc/pull/362>`_).
   - Emphasise that ``POST /tokenrefresh`` should expire the access token
     (`#363 <https://github.com/matrix-org/matrix-doc/pull/363>`_).
+  - Clarify the fields which are applicable to different types of push rule
+    (`#365 <https://github.com/matrix-org/matrix-doc/pull/365>`_).
 
 - Changes to the API which will be backwards-compatible for clients: