Update comments and doc

playwright/e2e/crypto/utils.ts

@@ -24,9 +24,8 @@ import { ElementAppPage } from "../../pages/ElementAppPage";
 import { Bot } from "../../pages/bot";
 
 /**
- * Create a bot client and wait for the key backup to be ready.
- * This function will wait for the key backup to be ready.
- * @param page - the page to use
+ * Create a bot client using the supplied credentials, and wait for the key backup to be ready.
+ * @param page - the playwright `page` fixture
  * @param homeserver - the homeserver to use
  * @param credentials - the credentials to use for the bot client
  */

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

@@ -62,6 +62,8 @@ export function ChangeRecoveryKey({
 }: ChangeRecoveryKeyProps): JSX.Element | null {
     const matrixClient = useMatrixClientContext();
 
+    // If the user is setting up recovery for the first time, we first show them a panel explaining what
+    // "recovery" is about. Otherwise, we jump straight to showing the user the new key.
     const [state, setState] = useState<State>(userHasKeyBackup ? "save_key_change_flow" : "inform_user");
 
     // We create a new recovery key, the recovery key will be displayed to the user
@@ -71,6 +73,7 @@ export function ChangeRecoveryKey({
     let content: JSX.Element;
     switch (state) {
         case "inform_user":
+            // Show a panel explaining what "recovery" is for, and what a recovery key does.
             content = (
                 <InformationPanel
                     onContinueClick={() => setState("save_key_setup_flow")}
@@ -80,6 +83,7 @@ export function ChangeRecoveryKey({
             break;
         case "save_key_setup_flow":
         case "save_key_change_flow":
+            // Show a generated recovery key and ask the user to save it.
             content = (
                 <KeyPanel
                     recoveryKey={recoveryKey.encodedPrivateKey}
@@ -89,6 +93,7 @@ export function ChangeRecoveryKey({
             );
             break;
         case "confirm":
+            // Ask the user to enter the recovery key they just save to confirm it.
             content = (
                 <KeyForm
                     recoveryKey={recoveryKey.encodedPrivateKey}

src/components/views/settings/tabs/SettingsTab.tsx

@@ -11,7 +11,7 @@ import classNames from "classnames";
 export interface SettingsTabProps extends HTMLAttributes<HTMLDivElement> {
     children?: React.ReactNode;
     /**
-     * Added to the root div
+     * Added to the classList of the root element
      */
     className?: string;
 }

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

@@ -24,7 +24,7 @@ import { SettingsSubheader } from "../../SettingsSubheader";
  *  - "loading": We are checking if the device is verified.
  *  - "main": The main panel with all the sections (Key storage, recovery, advanced).
  *  - "set_up_encryption": The panel to show when the user is setting up their encryption.
- *                         This happens when the user doesn't have cross-signing enabled.
+ *                         This happens when the user doesn't have cross-signing enabled, or their current device is not verified.
  *  - "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.
@@ -73,10 +73,15 @@ export function EncryptionUserSettingsTab(): JSX.Element {
 }
 
 /**
- * Hook to check if the user needs to set up their encryption for this session.
+ * Hook to check if the user needs to go through the SetupEncryption flow.
  * If the user needs to set up the encryption, the state will be set to "set_up_encryption".
  * Otherwise, the state will be set to "main".
- * @param setState
+ *
+ * The state is set once when the component is first mounted.
+ * Also returns a callback function which can be called to re-run the logic.
+ *
+ * @param setState - callback passed from the EncryptionUserSettingsTab to set the current `State`.
+ * @returns a callback function, which will re-run the logic and update the state.
  */
 function useSetUpEncryptionRequired(setState: (state: State) => void): () => Promise<void> {
     const matrixClient = useMatrixClientContext();
@@ -88,24 +93,30 @@ function useSetUpEncryptionRequired(setState: (state: State) => void): () => Pro
         else setState("set_up_encryption");
     }, [matrixClient, setState]);
 
+    // Initialise the state when the component is mounted
     useEffect(() => {
         setUpEncryptionRequired();
     }, [setUpEncryptionRequired]);
 
+    // Also return the callback so that the component can re-run the logic.
     return setUpEncryptionRequired;
 }
 
 interface SetUpEncryptionPanelProps {
     /**
-     * Callback to call when the user has finished to set up the encryption.
+     * Callback to call when the user has finished setting up encryption.
      */
     onFinish: () => void;
 }
 
 /**
- * Panel to show when the user needs to verify their session.
+ * Panel to show when the user needs to go through the SetupEncryption flow.
  */
 function SetUpEncryptionPanel({ onFinish }: SetUpEncryptionPanelProps): JSX.Element {
+    // Strictly speaking, the SetupEncryptionDialog may make the user do things other than
+    // verify their device (in particular, if they manage to get here without cross-signing keys existing);
+    // however the common case is that they will be asked to verify, so we just show buttons and headings
+    // that talk about verification.
     return (
         <SettingsSection
             legacy={false}