From 2fcc92c2fb9c0f460c59b3415ad0aba61bd16764 Mon Sep 17 00:00:00 2001
From: Hubert Chathi <hubertc@matrix.org>
Date: Thu, 17 Nov 2022 02:53:15 -0500
Subject: [PATCH] improve documentation of ephemeral events (#1284)

---
 changelogs/client_server/newsfragments/1284.clarification | 1 +
 data/api/client-server/definitions/sync_filter.yaml       | 5 +++--
 data/api/client-server/sync.yaml                          | 8 +++++---
 3 files changed, 9 insertions(+), 5 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1284.clarification

diff --git a/changelogs/client_server/newsfragments/1284.clarification b/changelogs/client_server/newsfragments/1284.clarification
new file mode 100644
index 000000000..bd52dbd4d
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1284.clarification
@@ -0,0 +1 @@
+Improve documentation about ephemeral events.
\ No newline at end of file
diff --git a/data/api/client-server/definitions/sync_filter.yaml b/data/api/client-server/definitions/sync_filter.yaml
index 0b4a8dca2..0ea6e9c2c 100644
--- a/data/api/client-server/definitions/sync_filter.yaml
+++ b/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
-          and receipts, to include for rooms.
+        description: The ephemeral events to include for rooms. These are the
+          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
diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml
index c36bafdbc..487a70191 100644
--- a/data/api/client-server/sync.yaml
+++ b/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
-                            recorded in the timeline or state of the room.
-                            e.g. typing.
+                            The new ephemeral events in the room (events that
+                            aren't recorded in the timeline or state of the
+                            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: