Documentation in MatrixChat and Lifecycle

Author: richvdh

src/Lifecycle.ts

@@ -599,6 +599,9 @@ async function abortLogin(): Promise<void> {
 }
 
 /** Attempt to restore the session from localStorage or indexeddb.
+ *
+ * If the credentials are found, and the session is successfully restored,
+ * emits {@link Action.OnLoggedIn}, {@link Action.WillStartClient} and {@link Action.StartedClient}.
  *
  * @returns true if a session was found; false if no existing session was found.
  *
@@ -787,6 +790,8 @@ async function createOidcTokenRefresher(credentials: IMatrixClientCreds): Promis
  * optionally clears localstorage, persists new credentials
  * to localstorage, starts the new client.
  *
+ * Emits {@link Action.OnLoggedIn}, {@link Action.WillStartClient} and {@link Action.StartedClient}.
+ *
  * @param {IMatrixClientCreds} credentials The credentials to use
  * @param {Boolean} clearStorageEnabled True to clear storage before starting the new client
  * @param {Boolean} isFreshLogin True if this is a fresh login, false if it is previous session being restored
@@ -1019,6 +1024,12 @@ export function isLoggingOut(): boolean {
  * Starts the matrix client and all other react-sdk services that
  * listen for events while a session is logged in.
  *
+ * By the time this method is called, we have successfully logged in if necessary, and the client has been set up with
+ * the access token.
+ *
+ * Emits {@link Acction.WillStartClient} before starting the client, and {@link Action.ClientStarted} when the client has
+ * been started.
+ *
  * @param client the matrix client to start
  * @param startSyncing - `true` to actually start syncing the client.
  * @param clientPegOpts - Options to pass through to {@link MatrixClientPeg.start}.

src/components/structures/MatrixChat.tsx

@@ -225,7 +225,13 @@ export default class MatrixChat extends React.PureComponent<IProps, IState> {
     private firstSyncPromise: PromiseWithResolvers<void>;
 
     private screenAfterLogin?: IScreen;
+
+    /** True if we have successfully completed an OIDC or token login.
+     *
+     * XXX it's unclear if this is ever cleared, so what happens if the user logs out and then logs back in?
+     */
     private tokenLogin?: boolean;
+
     // What to focus on next component update, if anything
     private focusNext: FocusNextType;
     private subTitleStatus: string;
@@ -386,6 +392,26 @@ export default class MatrixChat extends React.PureComponent<IProps, IState> {
         await Lifecycle.onSessionLockStolen();
     }
 
+    /**
+     * Perform actions that are specific to a user that has just logged in (compare {@link onLoggedIn}, which, despite
+     * its name, is called when an already-logged-in client is restored at session startup).
+     *
+     * Called when:
+     *
+     *  - We successfully completed an OIDC or token login, via {@link initSession}.
+     *  - The {@link Login} or {@link Register} components notify us that we successfully completed a non-OIDC login or
+     *    registration.
+     *
+     * In both cases, {@link Action.OnLoggedIn} will already have been emitted, but the call to {@link onLoggedIn} will
+     * have been suppressed (by either {@link tokenLogin} being set, or the view being set to {@link Views.LOGIN} or
+     * {@link Views.REGISTER}).
+     *
+     * {@link onWillStartClient} and {@link onClientStarted} will already have been called (but not necessarily
+     * completed).
+     *
+     * This method either calls {@link onLiggedIn} directly, or switches to {@link Views.E2E_SETUP} or
+     * {@link Views.COMPLETE_SECURITY}, which will later call {@link onCompleteSecurityE2eSetupFinished}.
+     */
     private async postLoginSetup(): Promise<void> {
         const cli = MatrixClientPeg.safeGet();
         const cryptoEnabled = Boolean(cli.getCrypto());
@@ -1369,7 +1395,15 @@ export default class MatrixChat extends React.PureComponent<IProps, IState> {
     }
 
     /**
-     * Called when a new logged in session has started
+     * Called when a new logged in session has started.
+     *
+     * Called:
+     *
+     *  - on {@link Action.OnLoggedIn}, but only when we don't expect a separate call to {@link postLoginSetup}.
+     *  - from {@link postLoginSetup}, when we don't have crypto setup tasks to perform after the login.
+     *
+     * It's never actually called if we have crypto setup tasks to perform after login (which we normally do, unless
+     * crypto is disabled.) XXX: is this a bug or a feature?
      */
     private async onLoggedIn(): Promise<void> {
         ThemeController.isLogin = false;
@@ -1379,6 +1413,16 @@ export default class MatrixChat extends React.PureComponent<IProps, IState> {
         await this.onShowPostLoginScreen();
     }
 
+    /**
+     * Show the first screen after the application is successfully loaded in a logged-in state.
+     *
+     * Called:
+     *
+     *  - by {@link onLoggedIn}
+     *  - by {@link onCompleteSecurityE2eSetupFinished}
+     *
+     * In other words, whenever we think we have completed the login and E2E setup tasks.
+     */
     private async onShowPostLoginScreen(): Promise<void> {
         this.setStateForNewView({ view: Views.LOGGED_IN });
         // If a specific screen is set to be shown after login, show that above
@@ -2043,7 +2087,7 @@ export default class MatrixChat extends React.PureComponent<IProps, IState> {
         PerformanceMonitor.instance.stop(PerformanceEntryNames.REGISTER);
     };
 
-    // complete security / e2e setup has finished
+    /** Called when {@link Views.E2E_SETUP} or {@link Views.COMPLETE_SECURITY} have completed. */
     private onCompleteSecurityE2eSetupFinished = async (): Promise<void> => {
         const forceVerify = await this.shouldForceVerification();
         if (forceVerify) {