docs: 📚️ use jsdoc for global.d.ts

apps/api/src/global.d.ts

@@ -1,13 +1,19 @@
-// These are the type declarations for the virtual modules
-// used by the `/courses/{id}` and `/instructors/{id}` routes.
-// The reason we have to use inline imports here is because with `import` statements, TypeScript
-// treats this as a normal module rather than an ambient module, and so the module declarations
-// don't actually work when consumed by other TypeScript source files.
+/**
+ * Ambient declaration file for defining "virtual" modules/files.
+ * The file contents are generated dynamically during build time by esbuild.
+ * DO NOT add any imports/exports; that converts the file to a regular module
+ * and removes the global declarations.
+ */
 
+/**
+ * Virtual module for caching course information during build time.
+ */
 declare module "virtual:courses" {
   declare const courses: Record<string, import("@peterportal-api/types").Course>;
 }
-
+/**
+ * Virtual module for caching instructor information during build time.
+ */
 declare module "virtual:instructors" {
   declare const instructors: Record<string, import("@peterportal-api/types").Instructor>;
 }