Merge pull request #6 from arpitchakladar/adding-documentation-comments

Adding documentation comments

6 files changed, 72 insertions, 12 deletions

diff --git a/config/webpack/utils/build-file.js b/config/webpack/utils/build-file.js
index 6945911..e09747d 100644
--- a/config/webpack/utils/build-file.js
+++ b/config/webpack/utils/build-file.js
@@ -1,6 +1,16 @@
 import crypto from "crypto";
 
-export const getFileName = (fileName, prefix, justHash = false) => {
+/**
+ * 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 function getFileName(fileName, prefix, justHash = false) {
 	let hash = crypto
 		.createHash("md5")
 		.update(`${prefix}-${fileName}`)
diff --git a/config/webpack/utils/injected-code.js b/config/webpack/utils/injected-code.js
index a2884f6..f2e51c8 100644
--- a/config/webpack/utils/injected-code.js
+++ b/config/webpack/utils/injected-code.js
@@ -1,13 +1,29 @@
 import crypto from "crypto";
 
-const getHash = url =>
+/**
+ * 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")
 		.update(url)
 		.digest("hex")
 		.substring(16);
 
-export const getInjectedCode = code => {
+/**
+ * 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 function getInjectedCode(code) {
 	const extensionAssets = {};
 	let i = 0;
 
@@ -34,7 +50,7 @@ export const getInjectedCode = code => {
 	}
 
 	const extensionAssetsCode = Object.entries(extensionAssets).map(
-		asset => `"${asset[0]}": chrome.runtime.getURL("${asset[1]}")`
+		(asset) => `"${asset[0]}": chrome.runtime.getURL("${asset[1]}")`
 	).join(",");
 
 	return [code, `{${extensionAssetsCode}}`];
diff --git a/config/webpack/utils/inline-javascript.js b/config/webpack/utils/inline-javascript.js
index 456dc11..501f852 100644
--- a/config/webpack/utils/inline-javascript.js
+++ b/config/webpack/utils/inline-javascript.js
@@ -1 +1,10 @@
-export const inlineJavascript = code => `data:text/javascript;base64,${Buffer.from(code).toString("base64")}`;
+/**
+ * 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 function inlineJavascript(code) {
+	return `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..2745d54 100644
--- a/config/webpack/utils/script-runtime.js
+++ b/config/webpack/utils/script-runtime.js
@@ -1,4 +1,15 @@
-export const getScriptRuntimeFromType = scriptType => {
+/**
+ * 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 function getScriptRuntimeFromType(scriptType) {
 	switch (scriptType) {
 		case "before":
 		case "injected-after":
diff --git a/config/webpack/utils/scripts.js b/config/webpack/utils/scripts.js
index af58e0a..d5a0cdc 100644
--- a/config/webpack/utils/scripts.js
+++ b/config/webpack/utils/scripts.js
@@ -1,10 +1,18 @@
-import path from "path";
 import fs from "fs";
+import path from "path";
 
+/**
+ * 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"),
-	),
+		path.resolve("./src/scripts.json")
+	)
 );
 
 const formattedScripts = {};
diff --git a/config/webpack/utils/shared-modules.js b/config/webpack/utils/shared-modules.js
index 2b16fa5..c9c9618 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";
+import path from "path";
 
+/**
+ * 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));
+	.filter((sharedModule) => !sharedModule.endsWith("import-shared.js"))
+	.map((sharedModule) => sharedModule.substring(0, sharedModule.length - 3));