Docs & cleanup

Author: turt2live

src/modules/AppModule.ts

@@ -14,14 +14,31 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-import { ModuleFactory } from "./ModuleFactory";
 import { RuntimeModule } from "@matrix-org/react-sdk-module-api/lib/RuntimeModule";
+
+import { ModuleFactory } from "./ModuleFactory";
 import { ProxiedModuleApi } from "./ProxiedModuleApi";
 
+/**
+ * Wraps a module factory into a usable module. Acts as a simple container
+ * for the constructs needed to operate a module.
+ */
 export class AppModule {
+    /**
+     * The module instance.
+     */
     public readonly module: RuntimeModule;
+
+    /**
+     * The API instance used by the module.
+     */
     public readonly api = new ProxiedModuleApi();
 
+    /**
+     * Converts a factory into an AppModule. The factory will be called
+     * immediately.
+     * @param factory The module factory.
+     */
     public constructor(factory: ModuleFactory) {
         this.module = factory(this.api);
     }

src/modules/ModuleComponents.tsx

@@ -14,13 +14,15 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// TODO: @@ Is this future-proof enough? Will we remember to do this for new components?
 import { TextInputField } from "@matrix-org/react-sdk-module-api/lib/components/TextInputField";
 import { Spinner as ModuleSpinner } from "@matrix-org/react-sdk-module-api/lib/components/Spinner";
 import React from "react";
+
 import Field from "../components/views/elements/Field";
 import Spinner from "../components/views/elements/Spinner";
 
+// TODO: @@ Is this future-proof enough? Will we remember to do this for new components?
+
 TextInputField.renderFactory = (props) => (
     <Field
         type="text"

src/modules/ModuleRunner.ts

@@ -15,11 +15,15 @@ limitations under the License.
 */
 
 import { TranslationStringsObject } from "@matrix-org/react-sdk-module-api/lib/types/translations";
+import { AnyLifecycle } from "@matrix-org/react-sdk-module-api/lib/lifecycles/types";
+
 import { AppModule } from "./AppModule";
 import { ModuleFactory } from "./ModuleFactory";
-import { AnyLifecycle } from "@matrix-org/react-sdk-module-api/lib/lifecycles/types";
 import "./ModuleComponents";
 
+/**
+ * Handles and coordinates the operation of modules.
+ */
 export class ModuleRunner {
     public static readonly instance = new ModuleRunner();
 
@@ -29,6 +33,9 @@ export class ModuleRunner {
         // we only want one instance
     }
 
+    /**
+     * All custom translations from all registered modules.
+     */
     public get allTranslations(): TranslationStringsObject {
         const merged: TranslationStringsObject = {};
 
@@ -47,10 +54,20 @@ export class ModuleRunner {
         return merged;
     }
 
+    /**
+     * Registers a factory which creates a module for later loading. The factory
+     * will be called immediately.
+     * @param factory The module factory.
+     */
     public registerModule(factory: ModuleFactory) {
         this.modules.push(new AppModule(factory));
     }
 
+    /**
+     * Invokes a lifecycle event, notifying registered modules.
+     * @param lifecycleEvent The lifecycle event.
+     * @param args The arguments for the lifecycle event.
+     */
     public invoke(lifecycleEvent: AnyLifecycle, ...args: any[]): void {
         for (const module of this.modules) {
             module.module.emit(lifecycleEvent, ...args);

src/modules/ProxiedModuleApi.ts

@@ -36,21 +36,37 @@ import { MatrixClientPeg } from "../MatrixClientPeg";
 import { getCachedRoomIDForAlias } from "../RoomAliasCache";
 import { Action } from "../dispatcher/actions";
 
+/**
+ * Glue between the `ModuleApi` interface and the react-sdk. Anticipates one instance
+ * to be assigned to a single module.
+ */
 export class ProxiedModuleApi implements ModuleApi {
     private cachedTranslations: Optional<TranslationStringsObject>;
 
+    /**
+     * All custom translations used by the associated module.
+     */
     public get translations(): Optional<TranslationStringsObject> {
         return this.cachedTranslations;
     }
 
+    /**
+     * @override
+     */
     public registerTranslations(translations: TranslationStringsObject): void {
         this.cachedTranslations = translations;
     }
 
+    /**
+     * @override
+     */
     public translateString(s: string, variables?: Record<string, PlainSubstitution>): string {
         return _t(s, variables);
     }
 
+    /**
+     * @override
+     */
     public openDialog<M extends object, P extends DialogProps = DialogProps, C extends React.Component = React.Component>(title: string, body: (props: P, ref: React.RefObject<C>) => React.ReactNode): Promise<{ didOkOrSubmit: boolean, model: M }> {
         return new Promise<{ didOkOrSubmit: boolean, model: M }>((resolve) => {
             Modal.createDialog(ModuleUiDialog, {
@@ -65,6 +81,9 @@ export class ProxiedModuleApi implements ModuleApi {
         });
     }
 
+    /**
+     * @override
+     */
     public async registerSimpleAccount(username: string, password: string, displayName?: string): Promise<AccountAuthInfo> {
         const hsUrl = SdkConfig.get("validated_server_config").hsUrl;
         const client = Matrix.createClient({ baseUrl: hsUrl });
@@ -101,13 +120,19 @@ export class ProxiedModuleApi implements ModuleApi {
         };
     }
 
+    /**
+     * @override
+     */
     public async overwriteAccountAuth(accountInfo: AccountAuthInfo): Promise<void> {
         await doSetLoggedIn({
             ...accountInfo,
             guest: false,
         }, true);
     }
 
+    /**
+     * @override
+     */
     public async navigatePermalink(uri: string, andJoin?: boolean): Promise<void> {
         navigateToPermalink(uri);
 
@@ -139,6 +164,9 @@ export class ProxiedModuleApi implements ModuleApi {
         }
     }
 
+    /**
+     * @override
+     */
     public getConfigValue<T>(namespace: string, key: string): T {
         // Force cast to `any` because the namespace won't be known to the SdkConfig types
         const maybeObj = SdkConfig.get(namespace as any);

src/stores/widgets/StopGapWidgetDriver.ts

@@ -46,7 +46,6 @@ import { WidgetType } from "../../widgets/WidgetType";
 import { CHAT_EFFECTS } from "../../effects";
 import { containsEmoji } from "../../effects/utils";
 import dis from "../../dispatcher/dispatcher";
-import { tryTransformPermalinkToLocalHref } from "../../utils/permalinks/Permalinks";
 import SettingsStore from "../../settings/SettingsStore";
 import { RoomViewStore } from "../RoomViewStore";
 import { ElementWidgetCapabilities } from "./ElementWidgetCapabilities";