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();
         }