Doc improvements from #29138 (#29503)

* Rename props & fix typo

* Docs

* Better docs

* Add comment

* Fix typo

* Paragraphs in tsdoc

* Add comment

* Hopefully clearer comment

* Really fix typo

Co-authored-by: Will Hunt <will@half-shot.uk>

* Stray word

Co-authored-by: Andy Balaam <andy.balaam@matrix.org>

* Hopefully clearer comment

* Typo

* Formatting & clarity

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

---------

Co-authored-by: Will Hunt <will@half-shot.uk>
Co-authored-by: Andy Balaam <andy.balaam@matrix.org>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

playwright/e2e/crypto/toasts.spec.ts

@@ -29,7 +29,9 @@ test.describe("Key storage out of sync toast", () => {
     });
 
     test("should prompt for recovery key if 'enter recovery key' pressed", { tag: "@screenshot" }, async ({ page }) => {
-        // Need to wait for 2 to appear since playwright only evaluates 'first()' initially, so the waiting won't work
+        // We need to wait for there to be two toasts as the wait below won't work in isolation:
+        // playwright only evaluates the 'first()' call initially, not subsequent times it checks, so
+        // it would always be checking the same toast, even if another one is now the first.
         await expect(page.getByRole("alert")).toHaveCount(2);
         await expect(page.getByRole("alert").first()).toMatchScreenshot("key-storage-out-of-sync-toast.png");
 

playwright/e2e/crypto/utils.ts

@@ -221,6 +221,9 @@ export async function logIntoElement(page: Page, credentials: Credentials, secur
         await page.locator(".mx_AuthPage").getByRole("button", { name: "Verify with Recovery Key" }).click();
 
         const useSecurityKey = page.locator(".mx_Dialog").getByRole("button", { name: "use your Recovery Key" });
+        // If the user has set a recovery *passphrase*, they'll be prompted for that first and have to click
+        // through to enter the recovery key which is what we have here. If they haven't, they'll be prompted
+        // for a recovery key straight away. We click the button if it's there so this works in both cases.
         if (await useSecurityKey.isVisible()) {
             await useSecurityKey.click();
         }

src/components/views/dialogs/UserSettingsDialog.tsx

@@ -50,6 +50,11 @@ import { EncryptionUserSettingsTab } from "../settings/tabs/user/EncryptionUserS
 interface IProps {
     initialTabId?: UserTab;
     showMsc4108QrCode?: boolean;
+    /**
+     * If `true`, the flow for a user to reset their encryption will be shown. In this case, `initialTabId` must be `UserTab.Encryption`.
+     *
+     * If false or undefined, show the tab as normal.
+     */
     showResetIdentity?: boolean;
     sdkContext: SdkContextClass;
     onFinished(): void;
@@ -92,7 +97,7 @@ function titleForTabID(tabId: UserTab): React.ReactNode {
 export default function UserSettingsDialog(props: IProps): JSX.Element {
     const voipEnabled = useSettingValue(UIFeature.Voip);
     const mjolnirEnabled = useSettingValue("feature_mjolnir");
-    // store these props in state as changing tabs back and forth should clear it
+    // store these props in state as changing tabs back and forth should clear them
     const [showMsc4108QrCode, setShowMsc4108QrCode] = useState(props.showMsc4108QrCode);
     const [showResetIdentity, setShowResetIdentity] = useState(props.showResetIdentity);
 

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

@@ -31,8 +31,10 @@ interface ResetIdentityPanelProps {
     /**
      * The variant of the panel to show. We show more warnings in the 'compromised' variant (no use in showing a user this
      * warning if they have to reset because they no longer have their key)
+     *
      * "compromised" is shown when the user chooses 'reset' explicitly in settings, usually because they believe their
      * identity has been compromised.
+     *
      * "forgot" is shown when the user has just forgotten their passphrase.
      */
     variant: "compromised" | "forgot";

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

@@ -37,7 +37,7 @@ import { DeleteKeyStoragePanel } from "../../encryption/DeleteKeyStoragePanel";
  *                           This happens when the user has a recovery key 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 a recovery key and the user clicks on "Set up recovery key" button of the RecoveryPanel.
- *  - "reset_identity_compromised": The panel to show when the user is resetting their identity, in te case where their key is compromised.
+ *  - "reset_identity_compromised": The panel to show when the user is resetting their identity, in the case where their key is compromised.
  *  - "reset_identity_forgot": The panel to show when the user is resetting their identity, in the case where they forgot their recovery key.
  *  - "secrets_not_cached": The secrets are not cached locally. This can happen if we verified another device and secret-gossiping failed, or the other device itself lacked the secrets.
  *                          If the "set_up_encryption" and "secrets_not_cached" conditions are both filled, "set_up_encryption" prevails.
@@ -55,9 +55,9 @@ export type State =
     | "secrets_not_cached"
     | "key_storage_delete";
 
-interface EncryptionUserSettingsTabProps {
+interface Props {
     /**
-     * If the tab should start in a state other than the deasult
+     * If the tab should start in a state other than the default
      */
     initialState?: State;
 }
@@ -65,7 +65,7 @@ interface EncryptionUserSettingsTabProps {
 /**
  * The encryption settings tab.
  */
-export function EncryptionUserSettingsTab({ initialState = "loading" }: EncryptionUserSettingsTabProps): JSX.Element {
+export function EncryptionUserSettingsTab({ initialState = "loading" }: Props): JSX.Element {
     const [state, setState] = useState<State>(initialState);
 
     const checkEncryptionState = useCheckEncryptionState(state, setState);

src/toasts/SetupEncryptionToast.ts

@@ -161,6 +161,7 @@ export const showToast = (kind: Kind): void => {
 
     const onSecondaryClick = (): void => {
         if (kind === Kind.KEY_STORAGE_OUT_OF_SYNC) {
+            // Open the user settings dialog to the encryption tab and start the flow to reset encryption
             const payload: OpenToTabPayload = {
                 action: Action.ViewUserSettings,
                 initialTabId: UserTab.Encryption,