From d572200cfb7519f66478bdb2f512ee22fe0bea30 Mon Sep 17 00:00:00 2001
From: Franz Liedke <franz@develophp.org>
Date: Fri, 18 Sep 2020 15:11:27 +0200
Subject: [PATCH] TS: Document shims files

---
 js/shims.d.ts                |  7 +++++++
 js/webpack-config-shims.d.ts | 17 +++++++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/js/shims.d.ts b/js/shims.d.ts
index ddc97cfde..9ec6409c5 100644
--- a/js/shims.d.ts
+++ b/js/shims.d.ts
@@ -1,7 +1,14 @@
+// Use shared globals from flarum-webpack-config
+// TEMPORARY: This will likely move to the flarum-webpack-config package.
 export * from './webpack-config-shims';
 
 import Application from './src/common/Application';
 
+/**
+ * Annotate the types of all global variables specific to flarum/core.
+ *
+ * IDEs can use this to typehint the globals.
+ */
 declare global {
   const app: Application;
 }
diff --git a/js/webpack-config-shims.d.ts b/js/webpack-config-shims.d.ts
index 978eb9662..a977ef9a6 100644
--- a/js/webpack-config-shims.d.ts
+++ b/js/webpack-config-shims.d.ts
@@ -4,16 +4,33 @@ import Stream from 'mithril/stream';
 import * as _dayjs from 'dayjs';
 import * as _$ from 'jquery';
 
+// Helpers that flarum/core patches into Mithril
 interface m extends Mithril.Static {
   prop: typeof Stream;
 }
 
+/**
+ * flarum/core exposes several extensions globally:
+ *
+ * - jQuery for convenient DOM manipulation
+ * - Mithril for VDOM and components
+ * - dayjs for date/time operations
+ *
+ * Since these are already part of the global namespace, extensions won't need
+ * to (and should not) bundle these themselves.
+ */
 declare global {
   const $: typeof _$;
   const m: m;
   const dayjs: typeof _dayjs;
 }
 
+/**
+ * Export Mithril typings globally.
+ *
+ * This lets us use these typings without an extra import everywhere we use
+ * Mithril in a TypeScript file.
+ */
 export as namespace Mithril;
 
 export {};