Document what all of our "Pegs" are (just singletons) (#8510)

As discussed at https://matrix.to/#/!fLeHeojWgBGJlLNdLC:matrix.org/$DHCPeZQ1aty_1l_nNHo_5F8Uwb3t29N1zuabWa5qLzM?via=matrix.org&via=element.io&via=vector.modular.im

Peg is used in the literal sense:

> a short pin or bolt, typically tapered at one end, that is used for securing something in place, hanging things on, or marking a position.

Looking for an `MatrixClient`? Just look for the `MatrixClientPeg` on the peg board. So you'll find a `MatrixClient` hanging on the `MatrixClientPeg`.

Maybe you're more familiar with these alternative names like `MatrixClientSingleton` but that's a bit long and Java-y or `MatrixClientHandle` in the win32 world.

src/MatrixClientPeg.ts

@@ -49,6 +49,12 @@ export interface IMatrixClientCreds {
     freshLogin?: boolean;
 }
 
+/**
+ * Holds the current instance of the `MatrixClient` to use across the codebase.
+ * Looking for an `MatrixClient`? Just look for the `MatrixClientPeg` on the peg
+ * board. "Peg" is the literal meaning of something you hang something on. So
+ * you'll find a `MatrixClient` hanging on the `MatrixClientPeg`.
+ */
 export interface IMatrixClientPeg {
     opts: IStartClientOpts;
 
@@ -311,6 +317,10 @@ class MatrixClientPegClass implements IMatrixClientPeg {
     }
 }
 
+/**
+ * Note: You should be using a React context with access to a client rather than
+ * using this, as in a multi-account world this will not exist!
+ */
 export const MatrixClientPeg: IMatrixClientPeg = new MatrixClientPegClass();
 
 if (!window.mxMatrixClientPeg) {

src/PlatformPeg.ts

@@ -18,11 +18,15 @@ limitations under the License.
 import BasePlatform from "./BasePlatform";
 
 /*
- * Holds the current Platform object used by the code to do anything
- * specific to the platform we're running on (eg. web, electron)
- * Platforms are provided by the app layer.
- * This allows the app layer to set a Platform without necessarily
- * having to have a MatrixChat object
+ * Holds the current instance of the `Platform` to use across the codebase.
+ * Looking for an `Platform`? Just look for the `PlatformPeg` on the peg board.
+ * "Peg" is the literal meaning of something you hang something on. So you'll
+ * find a `Platform` hanging on the `PlatformPeg`.
+ *
+ * Used by the code to do anything specific to the platform we're running on
+ * (eg. web, electron). Platforms are provided by the app layer. This allows the
+ * app layer to set a Platform without necessarily having to have a MatrixChat
+ * object.
  */
 export class PlatformPeg {
     platform: BasePlatform = null;

src/indexing/EventIndexPeg.ts

@@ -29,6 +29,12 @@ import { SettingLevel } from "../settings/SettingLevel";
 
 const INDEX_VERSION = 1;
 
+/**
+ * Holds the current instance of the `EventIndex` to use across the codebase.
+ * Looking for an `EventIndex`? Just look for the `EventIndexPeg` on the peg
+ * board. "Peg" is the literal meaning of something you hang something on. So
+ * you'll find a `EventIndex` hanging on the `EventIndexPeg`.
+ */
 export class EventIndexPeg {
     public index: EventIndex = null;
     public error: Error = null;