Add blurbs

Author: henrymercer

.github/actions/update-bundle/index.ts

@@ -1,3 +1,8 @@
+/*
+ * Updates src/defaults.json to point to a new CodeQL bundle release, and refreshes the
+ * snapshot of known language aliases in `src/known-language-aliases.json`.
+ */
+
 import * as github from '@actions/github';
 import * as fs from 'fs';
 import * as path from 'path';

.github/actions/update-bundle/language-aliases.ts

@@ -1,3 +1,13 @@
+/*
+ * The CodeQL CLI is the source of truth for language aliases. However, in some parts of the
+ * Action it is practical to resolve language aliases before the CodeQL CLI has been installed.
+ * Therefore we accept some duplication and store a snapshot of the known language aliases in
+ * `src/known-language-aliases.json`.
+ *
+ * This module handles downloading and extracting a CodeQL bundle, running the CLI to resolve
+ * language aliases, and writing the result back to `src/known-language-aliases.json`.
+ */
+
 import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
@@ -27,6 +37,8 @@ const KNOWN_LANGUAGE_ALIASES_PATH = path.resolve(
 export function assertSupportedPlatform(
   platform: NodeJS.Platform = process.platform
 ): void {
+  // We'll only ever run this on Linux in CI, but it's useful to support macOS too
+  // for local testing.
   if (platform !== 'linux' && platform !== 'darwin') {
     throw new Error(
       `The update-bundle script must run on Linux or macOS. Current platform: ${platform}.`
@@ -140,7 +152,7 @@ export async function updateKnownLanguageAliasesFromRelease(
     });
 
     const codeqlCliPath = path.join(extractDir, 'codeql', 'codeql');
-    console.log('Resolving language aliases using bundled CodeQL CLI');
+    console.log('Resolving language aliases using CodeQL CLI');
     const output = execFileSync(
       codeqlCliPath,
       ['resolve', 'languages', '--format=betterjson', '--extractor-include-aliases'],