incorporate review

api/server-server/definitions/event-schemas/m.device_list_update.yaml

@@ -30,7 +30,7 @@ allOf:
       edu_type:
         type: enum
         enum: ['m.device_list_update']
-        description: The string ``m.device_list_update``
+        description: The string ``m.device_list_update``.
         example: "m.device_list_update"
       content:
         type: object
@@ -55,7 +55,7 @@ allOf:
             type: integer
             description: |-
               An ID sent by the server for this update, unique for a given
-              user_id.  Used to identify any gaps in the sequence of m.device_list_update
+              user_id.  Used to identify any gaps in the sequence of ``m.device_list_update``
               EDUs broadcast by a server.
             example: 6
           prev_id:
@@ -65,7 +65,7 @@ allOf:
               which have not been referred to already in an EDU's prev_id field.  If the
               receiving server does not recognise any of the prev_ids, it means an EDU
               has been lost and the server should query a snapshot of the devicelist
-              via /user/keys/query in order to correctly interpret future m.device_list_update
+              via ``/user/keys/query`` in order to correctly interpret future ``m.device_list_update``
               EDUs.  May be missing or empty for the first EDU in a sequence.
             items:
               type: integer
@@ -82,8 +82,7 @@ allOf:
             description: |-
               The updated identity keys (if any) for this device.  May be absent if the
               device has no E2E keys defined.
-            allOf:
+            $ref: ../../../client-server/definitions/device_keys.yaml
-              - $ref: ../../../client-server/definitions/device_keys.yaml
         required:
           - user_id
           - device_id

specification/server_server_api.rst

@@ -1008,14 +1008,14 @@ of the Client-Server API.
 Matrix currently uses a custom pubsub system for synchronising information
 about the list of devices for a given user over federation.  When a server
 wishes to determine a remote user's device list for the first time,
-it should populate its local cache by calling the /user/keys/query API
+it should populate its local cache by calling the ``/user/keys/query`` API
 on the remote server.  However, subsequent updates to the cache should be applied
 by consuming ``m.device_list_update`` EDUs, which must be sent by the remote server
 whenever a user's device list changes.
 
 Servers send ``m.device_list_update`` EDUs in a sequence per source user, each with
 a unique ``stream_id``.  They also include a pointer to the most recent previous EDU(s)
-that this update is relative to in the `pprev_id`` field.  To simplify implementation
+that this update is relative to in the ``prev_id`` field.  To simplify implementation
 for clustered servers which could send multiple EDUs at the same time, the ``prev_id``
 field should include all ``m.device_list_update`` EDUs which have not been yet been
 referenced in a EDU. If EDUs are emitted in series by a server, there should only ever
@@ -1025,7 +1025,7 @@ This forms a simple directed acyclic graph of ``m.device_list_update`` EDUs, sho
 which EDUs a server needs to have received in order to apply an update to its local
 copy of the remote user's device list.  If a server receives an EDU which refers to
 a ``prev_id`` it does not recognise, it must resynchronise its list by calling the
-/user/keys/query API and resume the process.  The response contains a ``stream_id``
+``/user/keys/query API`` and resume the process.  The response contains a ``stream_id``
 which should be used to correlate with subsequent ``m.device_list_update`` EDUs.
 
 .. TODO: this whole thing desperately feels like it should just be state in a room,