add links from the Client-Server spec to the Olm message definitions (#2381)

* add links from the Client-Server spec to the Olm message definitions

* add newsfragment

changelogs/client_server/newsfragments/2381.clarification

@@ -0,0 +1 @@
+Add links from the Client-Server spec to the Olm message definitions.

changelogs/client_server/newsfragments/2382.clarification

@@ -0,0 +1 @@
+Disambiguate placeholder descriptions in OlmPayload example.

changelogs/client_server/newsfragments/2383.clarification

@@ -0,0 +1 @@
+Replace "Olm message" with "event encrypted using Olm" where not referring to the Olm message format.

content/client-server-api/modules/end_to_end_encryption.md

@@ -1623,9 +1623,9 @@ An event encrypted using Olm has the following format:
 ```
 
 `ciphertext` is a mapping from device Curve25519 key to an encrypted
-payload for that device. `body` is a Base64-encoded Olm message body.
+payload for that device. `body` is a Base64-encoded [Olm message body](/olm-megolm/olm/#the-olm-message-format).
 `type` is an integer indicating the type of the message body: 0 for the
-initial pre-key message, 1 for ordinary messages.
+initial [pre-key message](/olm-megolm/olm/#pre-key-messages), 1 for [normal messages](/olm-megolm/olm/#normal-messages).
 
 Olm sessions will generate messages with a type of 0 until they receive
 a message. Once a session has decrypted a message it will produce
@@ -1698,7 +1698,7 @@ Curve25519 key used to establish the Olm session does indeed belong
 to the claimed `sender`. This requires a signed "device keys" structure
 for that Curve25519 key, which can be obtained in one of two ways:
 
-1.  An Olm message may be received with a `sender_device_keys` property
+1.  An event encrypted using Olm may be received with a `sender_device_keys` property
     in the decrypted content.
 2.  The keys are returned via a [`/keys/query`](#post_matrixclientv3keysquery)
     request. Note that both the Curve25519 key **and** the Ed25519 key in

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

@@ -16,7 +16,7 @@
 type: object
 title: OlmPayload
 description: |-
-  The plaintext payload of Olm message events.
+  The plaintext payload of an event encrypted using Olm.
 properties:
   type:
     type: string
@@ -65,15 +65,15 @@ example: {
   "sender": "<sender_user_id>",
   "recipient": "<recipient_user_id>",
   "recipient_keys": {
-    "ed25519": "<our_ed25519_key>"
+    "ed25519": "<recipient_ed25519_key>"
   },
   "keys": {
     "ed25519": "<sender_ed25519_key>"
   },
   "sender_device_keys": {
     "algorithms": ["<supported>", "<algorithms>"],
-    "user_id": "<user_id>",
+    "user_id": "<sender_user_id>",
-    "device_id": "<device_id>",
+    "device_id": "<sender_device_id>",
     "keys": {
       "ed25519:<device_id>": "<sender_ed25519_key>",
       "curve25519:<device_id>": "<sender_curve25519_key>"