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;