From 8add540f2788f7bff8d6b53abcf6006d7a289754 Mon Sep 17 00:00:00 2001
From: Eric Eastwood <erice@element.io>
Date: Mon, 9 May 2022 21:34:27 -0500
Subject: [PATCH] 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        | 10 ++++++++++
 src/PlatformPeg.ts            | 14 +++++++++-----
 src/indexing/EventIndexPeg.ts |  6 ++++++
 3 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/src/MatrixClientPeg.ts b/src/MatrixClientPeg.ts
index 8657009016..a281ba6562 100644
--- a/src/MatrixClientPeg.ts
+++ b/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) {
diff --git a/src/PlatformPeg.ts b/src/PlatformPeg.ts
index 1d2b813ebc..14714a1d34 100644
--- a/src/PlatformPeg.ts
+++ b/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;
diff --git a/src/indexing/EventIndexPeg.ts b/src/indexing/EventIndexPeg.ts
index dc933808b2..097a86fbc1 100644
--- a/src/indexing/EventIndexPeg.ts
+++ b/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;