docs: added some documentation comments to all functions

6 files changed, 58 insertions, 0 deletions

diff --git a/config/webpack/utils/build-file.js b/config/webpack/utils/build-file.js
index 6945911..17f0b03 100644
--- a/config/webpack/utils/build-file.js
+++ b/config/webpack/utils/build-file.js
@@ -1,5 +1,15 @@
 import crypto from "crypto";
 
+/**
+ * Generates a deterministic output filename for a module.
+ * In production the result is a short MD5 hash; in development the
+ * original name is preserved alongside the hash for easier debugging.
+ *
+ * @param {string} fileName   - The original module filename.
+ * @param {string} prefix     - A namespace prefix (e.g. "shared", "injected").
+ * @param {boolean} justHash  - When true, always return only the hash part.
+ * @returns {string} The transformed filename.
+ */
 export const getFileName = (fileName, prefix, justHash = false) => {
 	let hash = crypto
 		.createHash("md5")
diff --git a/config/webpack/utils/injected-code.js b/config/webpack/utils/injected-code.js
index a2884f6..2b8f750 100644
--- a/config/webpack/utils/injected-code.js
+++ b/config/webpack/utils/injected-code.js
@@ -1,5 +1,12 @@
 import crypto from "crypto";
 
+/**
+ * Computes an MD5 hash suffix (last 16 hex characters) for a given URL.
+ * Used to create unique attribute names for injected script data.
+ *
+ * @param {string} url - The URL to hash.
+ * @returns {string} A 16-character hex hash.
+ */
 const getHash = url =>
 	crypto
 		.createHash("md5")
@@ -7,6 +14,15 @@ const getHash = url =>
 		.digest("hex")
 		.substring(16);
 
+/**
+ * Transforms extension asset URL placeholders (`"$l{ url }l$"`) in the
+ * compiled JavaScript into `document.currentScript.getAttribute("data-<hash>")`
+ * lookups.  The mapping of hashes to resolved `chrome.runtime.getURL()` calls
+ * is returned separately so the injector script can embed it as data attributes.
+ *
+ * @param {string} code - The compiled JavaScript bundle.
+ * @returns {[string, string]} A tuple of [transformedCode, extensionAssetsJSON].
+ */
 export const getInjectedCode = code => {
 	const extensionAssets = {};
 	let i = 0;
diff --git a/config/webpack/utils/inline-javascript.js b/config/webpack/utils/inline-javascript.js
index 456dc11..205bda4 100644
--- a/config/webpack/utils/inline-javascript.js
+++ b/config/webpack/utils/inline-javascript.js
@@ -1 +1,8 @@
+/**
+ * Wraps JavaScript source code in a base64-encoded data URI so it can be
+ * used as an inline webpack entry point without writing a physical file.
+ *
+ * @param {string} code - The JavaScript source to inline.
+ * @returns {string} A `data:text/javascript;base64,…` URI.
+ */
 export const inlineJavascript = code => `data:text/javascript;base64,${Buffer.from(code).toString("base64")}`;
diff --git a/config/webpack/utils/script-runtime.js b/config/webpack/utils/script-runtime.js
index a7c02f7..1c23922 100644
--- a/config/webpack/utils/script-runtime.js
+++ b/config/webpack/utils/script-runtime.js
@@ -1,3 +1,14 @@
+/**
+ * Maps a human-readable script type to a Chrome content-script
+ * `run_at` value.
+ *
+ * - `"before"`, `"injected-after"`, `"injected-before"` → `document_start`
+ * - `"rendered"` → `document_end`
+ * - `"loaded"` (or unknown) → `document_idle`
+ *
+ * @param {string} scriptType - The script type from scripts.json.
+ * @returns {string} The corresponding `run_at` value.
+ */
 export const getScriptRuntimeFromType = scriptType => {
 	switch (scriptType) {
 		case "before":
diff --git a/config/webpack/utils/scripts.js b/config/webpack/utils/scripts.js
index af58e0a..09a2fc0 100644
--- a/config/webpack/utils/scripts.js
+++ b/config/webpack/utils/scripts.js
@@ -1,6 +1,14 @@
 import path from "path";
 import fs from "fs";
 
+/**
+ * Reads `src/scripts.json` and re-indexes it so the outer key is the
+ * URL path fragment and the inner key is the script type.  This makes it
+ * trivial to look up which scripts run on which page.
+ *
+ * @returns {Record<string, Record<string, string[]>>} e.g.
+ *   `{ "*": { "injected": ["stop-blocking.ts"] }, "MuteApplication.action": … }`
+ */
 const scripts = JSON.parse(
 	fs.readFileSync(
 		path.resolve("./src/scripts.json"),
diff --git a/config/webpack/utils/shared-modules.js b/config/webpack/utils/shared-modules.js
index 2b16fa5..74ee555 100644
--- a/config/webpack/utils/shared-modules.js
+++ b/config/webpack/utils/shared-modules.js
@@ -1,6 +1,12 @@
 import path from "path";
 import fs from "fs";
 
+/**
+ * Scans `src/shared/` and returns the list of shared module filenames
+ * (with the `.ts` extension stripped), excluding `import-shared.js`.
+ *
+ * @returns {string[]} e.g. `["generate-web-page", "intercept-jquery-ajax", …]`
+ */
 export default fs.readdirSync(path.resolve("src/shared"))
 	.filter(sharedModule => !sharedModule.endsWith("import-shared.js"))
 	.map(sharedModule => sharedModule.substring(0, sharedModule.length - 3));