add more code comments

Author: matthewbastien

scripts/lib/utilities.ts

@@ -2,7 +2,7 @@
 //
 // This source file is part of the VS Code Swift open source project
 //
-// Copyright (c) 2024 the VS Code Swift project authors
+// Copyright (c) 2025 the VS Code Swift project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -15,6 +15,29 @@
 
 import * as child_process from "child_process";
 
+/**
+ * Executes the provided main function for the script while logging any errors.
+ *
+ * If an error is caught then the process will exit with code 1.
+ *
+ * @param mainFn The main function of the script that will be run.
+ */
+export async function main(mainFn: () => Promise<void>): Promise<void> {
+    try {
+        await mainFn();
+    } catch (error) {
+        console.error(error);
+        process.exit(1);
+    }
+}
+
+/**
+ * Executes the given command, inheriting the current process' stdio.
+ *
+ * @param command The command to execute.
+ * @param args The arguments to provide to the command.
+ * @param options The options for executing the command.
+ */
 export async function exec(
     command: string,
     args: string[],

scripts/preview_package.ts

@@ -2,7 +2,7 @@
 //
 // This source file is part of the VS Code Swift open source project
 //
-// Copyright (c) 2024 the VS Code Swift project authors
+// Copyright (c) 2025 the VS Code Swift project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -16,7 +16,7 @@
 import * as path from "path";
 import * as semver from "semver";
 import { readFile } from "fs/promises";
-import { exec } from "./lib/utilities";
+import { exec, main } from "./lib/utilities";
 
 /**
  * Formats the given date as a string in the form "YYYYMMddhhmm".
@@ -33,7 +33,7 @@ function formatDate(date: Date): string {
     return year + month + day + hour + minutes;
 }
 
-(async () => {
+main(async () => {
     const rootDirectory = path.join(__dirname, "..");
     // Grab the existing version number from the package.json
     const packageJSON = JSON.parse(
@@ -55,7 +55,4 @@ function formatDate(date: Date): string {
         ["vsce", "package", "--pre-release", "--no-update-package-json", previewVersion],
         { cwd: rootDirectory }
     );
-})().catch(error => {
-    console.error(error);
-    process.exit(1);
 });

scripts/update_swift_docc_render.ts

@@ -18,7 +18,7 @@ import { stat, mkdtemp, mkdir, rm, readdir } from "fs/promises";
 import * as path from "path";
 import { tmpdir } from "os";
 import * as semver from "semver";
-import { exec } from "./lib/utilities";
+import { exec, main } from "./lib/utilities";
 
 function checkNodeVersion() {
     const nodeVersion = semver.parse(process.versions.node);
@@ -57,7 +57,7 @@ async function cloneSwiftDocCRender(buildDirectory: string): Promise<string> {
     return swiftDocCRenderDirectory;
 }
 
-(async () => {
+main(async () => {
     const outputDirectory = path.join(__dirname, "..", "assets", "swift-docc-render");
     if (process.argv.includes("postinstall")) {
         try {
@@ -88,7 +88,4 @@ async function cloneSwiftDocCRender(buildDirectory: string): Promise<string> {
             console.error(error);
         });
     }
-})().catch(error => {
-    console.error(error);
-    process.exit(1);
 });