Improve wording on push gateways

api/client-server/pusher.yaml

@@ -226,12 +226,11 @@ paths:
                   format:
                     type: string
                     description: |-
-                      The format to send notifications in to Push Gateways. If
-                      unset or unrecognized, the homeserver should populate as
-                      many fields as it can in the push notification. If set to
-                      ``"event_id_only"``, the homeserver should only send the
-                      absolute minimum amount of information possible to the push
-                      gateway by not including optional fields.
+                      The format to send notifications in to Push Gateways if the
+                      ``kind`` is ``http``. The details about what fields the
+                      homeserver should send to the push gateway are defined in the
+                      `Push Gateway Specification`_. Currently the only format
+                      available is 'event_id_only'.
               append:
                 type: boolean
                 description: |-

api/push-gateway/push_notifier.yaml

@@ -145,9 +145,9 @@ paths:
                     type: object
                     title: EventContent
                     description: |-
-                      The ``content`` field from the event, if present. If the
-                      event had no content field or the pusher wishes to not include
-                      it, this field is omitted.
+                      The ``content`` field from the event, if present. The pusher
+                      may omit this if the event had no content or for any other
+                      reason.
                   counts:
                     type: object
                     title: Counts

specification/modules/push.rst

@@ -65,9 +65,6 @@ APNS or Google's GCM. This happens as follows:
    notifications.
 5. The Push Provider sends the notification to the device.
 
-Homeservers may optionally support email notifications or other push kinds
-of push, identified by the ``kind`` field of the pusher configuration.
-
 Definitions for terms used in this section are below:
 
 Push Provider
@@ -625,3 +622,5 @@ shouldn't be sent in the push itself where possible. Instead, Push Gateways
 should send a "sync" command to instruct the client to get new events from the
 homeserver directly.
 
+
+.. _`Push Gateway Specification`: ../push_gateway/unstable.html

specification/push_gateway.rst

@@ -67,4 +67,9 @@ This describes the format used by "HTTP" pushers to send notifications of
 events to Push Gateways. If the endpoint returns an HTTP error code, the
 homeserver SHOULD retry for a reasonable amount of time using exponential backoff.
 
+When pushing notifications for events, the hoemserver is expected to include all of
+the event-related fields in the ``/notify`` request. When the homeserver is performing
+a push where the ``format`` is ``"event_id_only"``, only the ``event_id``, ``room_id``,
+``counts``, and ``devices`` are required to be populated.
+
 {{push_notifier_push_http_api}}