From 5f3ee44cfbcfbdf625170788ad7fb8d91627d5fc Mon Sep 17 00:00:00 2001
From: Hubert Chathi <hubert@uhoreg.ca>
Date: Tue, 5 May 2020 18:09:17 -0400
Subject: [PATCH] add more suggestions from review

---
 api/client-server/key_backup.yaml               | 14 ++++++++++----
 specification/modules/end_to_end_encryption.rst |  4 ++--
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/api/client-server/key_backup.yaml b/api/client-server/key_backup.yaml
index bdca769e..ae729d62 100644
--- a/api/client-server/key_backup.yaml
+++ b/api/client-server/key_backup.yaml
@@ -73,7 +73,7 @@ paths:
             properties:
               version:
                 type: string
-                description: The backup version.
+                description: The backup version. This is an opaque string.
                 example: "1"
             required:
               - version
@@ -92,8 +92,10 @@ paths:
           type: string
           name: version
           description: |-
-            The backup version to get. When an empty string, the trailing slash
-            is optional, and the current backup is returned.
+            The backup version to get, as returned in the ``version`` parameter
+            of the response in `POST /_matrix/client/r0/room_keys/version`_ or
+            this endpoint. When an empty string, the trailing slash is
+            optional, and the current backup is returned.
           required: true
           x-example: "1"
       responses:
@@ -168,7 +170,11 @@ paths:
           type: string
           name: version
           description: |-
-            The backup version to update.
+            The backup version to update, as returned in the ``version``
+            parameter in the response of `POST
+            /_matrix/client/r0/room_keys/version`_ or `GET
+            /_matrix/client/r0/room_keys/version/{version}`_. Unlike with the
+            ``GET`` version of this endpoint, this may not be empty.
           required: true
           x-example: "1"
         - in: body
diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst
index 6945ce42..8e4b0739 100644
--- a/specification/modules/end_to_end_encryption.rst
+++ b/specification/modules/end_to_end_encryption.rst
@@ -819,8 +819,8 @@ follows:
 2. All the bytes in the string above, including the two header bytes, are XORed
    together to form a parity byte. This parity byte is appended to the byte
    string.
-3. The byte string is encoded using base58, using the same mapping as is used
-   for Bitcoin addresses.
+3. The byte string is encoded using base58, using the same `mapping as is used
+   for Bitcoin addresses <https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart>`_.
 4. A space should be added after every 4th character.
 
 When reading in a recovery key, clients must disregard whitespace, and perform