TS: Document shims files

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;
 }

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 {};