Specify the order in which one-time keys are returned (MSC4225)

Signed-off-by: Andy Balaam <[email protected]>

changelogs/client_server/newsfragments/2029.clarification

@@ -0,0 +1 @@
+Specify order of one-time keys, as per [MSC4225](https://github.com/matrix-org/matrix-spec-proposals/pull/4225).

data/api/client-server/keys.yaml

@@ -288,7 +288,17 @@ paths:
   /keys/claim:
     post:
       summary: Claim one-time encryption keys.
-      description: Claims one-time keys for use in pre-key messages.
+      description: |-
+        Claims one-time keys for use in pre-key messages.
+
+        The request contains the user ID, device ID and algorithm name of the
+        keys that are required. The response contains a key matching this -
+        either a one-time key, or if none are available, a fallback key.
+
+        One-time keys are given out in the order that they were uploaded via
+        [/keys/upload](/client-server-api/#post_matrixclientv3keysupload). (All
+        keys uploaded within a given call to `/keys/upload` are considered
+        equivalent in this regard; no ordering is specified within them.)
       operationId: claimKeys
       security:
         - accessTokenQuery: []

data/api/server-server/user_keys.yaml

@@ -20,7 +20,17 @@ paths:
   /user/keys/claim:
     post:
       summary: Claims one-time encryption keys for a user.
-      description: Claims one-time keys for use in pre-key messages.
+      description: |-
+        Claims one-time keys for use in pre-key messages.
+
+        The request contains the user ID, device ID and algorithm name of the
+        keys that are required. The response contains a key matching this -
+        either a one-time key, or if none are available, a fallback key.
+
+        One-time keys are given out in the order that they were uploaded via
+        [/keys/upload](/client-server-api/#post_matrixclientv3keysupload). (All
+        keys uploaded within a given call to `/keys/upload` are considered
+        equivalent in this regard; no ordering is specified within them.)
       operationId: claimUserEncryptionKeys
       security:
         - signedRequest: []