Fix docs

playwright/e2e/settings/encryption-user-tab/index.ts

@@ -68,7 +68,7 @@ class Helpers {
     }
 
     /**
-     * Set the default key id of the secret storage at null
+     * Set the default key id of the secret storage to `null`
      */
     async removeSecretStorageDefaultKeyId() {
         const client = await this.app.client.prepareClient();

playwright/e2e/settings/encryption-user-tab/recovery.spec.ts

@@ -120,8 +120,10 @@ test.describe("Recovery section in Encryption tab", () => {
         await checkDeviceIsConnectedKeyBackup(page, "2", true);
     });
 
-    // This case shouldn't happen but we have seen cases where the secrets gossiping failed or shared partial secrets when verified with another device.
-    // To simulate this case, we need to delete the cached secrets in the indexedDB
+    // Test what happens if the cross-signing secrets are in secret storage but are not cached in the local DB.
+    //
+    // This can happen if we verified another device and secret-gossiping failed, or the other device itself lacked the secrets.
+    // We simulate this case by deleting the cached secrets in the indexedDB.
     test(
         "should enter the recovery key when the secrets are not cached",
         { tag: "@screenshot" },

src/components/views/settings/encryption/ChangeRecoveryKey.tsx

@@ -108,7 +108,7 @@ export function ChangeRecoveryKey({
             break;
         case "confirm_key_setup_flow":
         case "confirm_key_change_flow":
-            // Ask the user to enter the recovery key they just save to confirm it.
+            // Ask the user to enter the recovery key they just saved to confirm it.
             content = (
                 <KeyForm
                     // encodedPrivateKey is always defined, the optional typing is incorrect

src/components/views/settings/encryption/RecoveryPanel.tsx

@@ -21,14 +21,17 @@ import { SettingsSubheader } from "../SettingsSubheader";
  * - `loading`: We are checking the recovery key and the secrets.
  * - `missing_recovery_key`: The user has no recovery key.
  * - `secrets_not_cached`: The user has a backup but the secrets are not cached.
- *                         This shouldn't happen but we have seen cases where the secrets gossiping failed or shared partial secrets when verified with another device.
- * - `good`: The user has a backup and the secrets are cached.
+ *                         This can happen if we verified another device and secret-gossiping failed, or the other device itself lacked the secrets.
+ * - `good`: The user has a recovery key and the secrets are cached.
  */
 type State = "loading" | "missing_recovery_key" | "secrets_not_cached" | "good";
 
 interface RecoveryPanelProps {
     /**
      * Callback for when the user wants to set up or change their recovery key.
+     *
+     * @param setupNewKeyis set if the user does not already have a recovery key (and has therefore clicked on
+     * "Set up recovery" rather than "Change recovery key").
      */
     onChangeRecoveryKeyClick: (setupNewKey: boolean) => void;
 }
@@ -45,7 +48,7 @@ export function RecoveryPanel({ onChangeRecoveryKeyClick }: RecoveryPanelProps):
     const checkEncryption = useCallback(async () => {
         const crypto = matrixClient.getCrypto()!;
 
-        // Check if the user has a backup
+        // Check if the user has a recovery key
         const hasRecoveryKey = Boolean(await matrixClient.secretStorage.getDefaultKeyId());
         if (!hasRecoveryKey) return setState("missing_recovery_key");
 

src/components/views/settings/tabs/user/EncryptionUserSettingsTab.tsx

@@ -28,7 +28,7 @@ import { SettingsSubheader } from "../../SettingsSubheader";
  *  - "change_recovery_key": The panel to show when the user is changing their recovery key.
  *                           This happens when the user has a key backup and the user clicks on "Change recovery key" button of the RecoveryPanel.
  *  - "set_recovery_key": The panel to show when the user is setting up their recovery key.
- *                        This happens when the user doesn't have a key backup and the user clicks on "Set up recovery key" button of the RecoveryPanel.
+ *                        This happens when the user doesn't have a key a recovery key and the user clicks on "Set up recovery key" button of the RecoveryPanel.
  */
 type State = "loading" | "main" | "set_up_encryption" | "change_recovery_key" | "set_recovery_key";