Clarify what is returned by the API.

Author: clokep

proposals/3856-threads-list-api.md

@@ -22,27 +22,40 @@ paginate through all of the threads in the room, inspect the latest event from
 the bundled aggregations and attempt to sort them. This can require many round
 trips to the server and is wasteful for both the client and server.
 
-Additionally, even with all of the threads a client is not able to accurately
-sort the threads since they lack the proper topological ordering of events. (The
-closest they can get is by using `age` or `origin_server_ts`, but this is not
-correct.)
-
-For the second problem, it is currently not possible for a client to query for
-threads that the user has participated in (as defined in
-[MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md#event-format)).
-A client could add the user's MXID to the filter, e.g. `"related_by_senders":["@alice:example.com"]`,
-but this misses threads where the user sent the root message and has not yet replied.
+Unfortunately even when a client has all the threads in a room is not able to accurately
+sort the threads since the client lacks the proper topological ordering of events. (The
+closest available information is the `age` or `origin_server_ts` of the events, but this
+is not always correct.)
+
+Additionally, it is currently not possible for a client to query for threads that
+the user has participated in, as defined in
+[MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md#event-format):
+
+> The user has participated if:
+>
+> * They created the current event.
+> * They created an event with a m.thread relation targeting the current event.
+
+Currently, clients add the requesting user's MXID to the `related_by_senders` filter
+(as defined in
+[MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md#fetch-all-threads-in-a-room)),
+e.g. `"related_by_senders":["@alice:example.com"]`, but this results in missing
+threads where the user sent the root message and has not yet replied.
 
 ## Proposal
 
 ### Client-Server endpoint
 
 A new endpoint is proposed to query for threads in a room. This endpoint requires
-authentication and is subject to rate-limiting. This endpoint includes
+authentication and is subject to rate-limiting.
+
+The endpoint returns events, which represent thread roots and includes
 [bundled aggregations](https://spec.matrix.org/v1.3/client-server-api/#aggregations)
-in the response.
+in the response (which includes the "latest event" of each thread, see
+[MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md#event-format)
+for the format of bundled aggregations of threads).
 
-The returned threads are ordered by the most recently updated thread.
+The returned events are ordered by the latest event of each thread.
 
 #### Request format
 
@@ -54,9 +67,10 @@ Query Parameters:
 
 * **`include`**: `enum`
 
-  Whether to include all threads in the room or only threads which the user has
-  participated in, meaning that the user has created the root event of the thread
-  or have created an event with a `m.thread` relation targeting the root.
+  Whether to include all thread roots in the room or only thread roots which the
+  user has participated in, meaning that the user has created the root event of
+  the thread or replied to the thread (they have created an event with a `m.thread`
+  relation targeting the root event).
 
   One of `[all participated]`. Defaults to `all`.
 * **`from`**: `string`
@@ -65,8 +79,8 @@ Query Parameters:
   `prev_batch` or `next_batch` token returned by the `/sync` endpoint, or from
   an `end` token returned by a previous request to this endpoint.
 
-  If it is not provided, the homeserver shall return a list of threads from the
-  last visible event in the room history for the requesting user.
+  If it is not provided, the homeserver shall return a list of thread roots starting
+  from the last visible event in the room history for the requesting user.
 * **`limit`**: Optional: a client-defined limit to the maximum
   number of threads to return per page. Must be an integer greater than zero.