improve documentation of ephemeral events (#1284)

changelogs/client_server/newsfragments/1284.clarification

@@ -0,0 +1 @@
+Improve documentation about ephemeral events.

data/api/client-server/definitions/sync_filter.yaml

@@ -62,8 +62,9 @@ properties:
       ephemeral:
         allOf:
         - $ref: room_event_filter.yaml
-        description: The events that aren't recorded in the room history, e.g. typing
+        description: The ephemeral events to include for rooms. These are the
-          and receipts, to include for rooms.
+          events that appear in the `ephemeral` property in the `/sync`
+          response.
       include_leave:
         description: Include rooms that the user has left in the sync, default false
         type: boolean

data/api/client-server/sync.yaml

@@ -219,9 +219,11 @@ paths:
                           title: Ephemeral
                           type: object
                           description: |-
-                            The ephemeral events in the room that aren't
+                            The new ephemeral events in the room (events that
-                            recorded in the timeline or state of the room.
+                            aren't recorded in the timeline or state of the
-                            e.g. typing.
+                            room). In this version of the spec, these are
+                            [typing notification](#typing-notifications) and
+                            [read receipt](#receipts) events.
                           allOf:
                             - $ref: "definitions/event_batch.yaml"
                         account_data: