6 files changed, 71 insertions, 0 deletions
diff --git a/src/shared/generate-web-page.ts b/src/shared/generate-web-page.ts
index a07575f..990f430 100644
--- a/src/shared/generate-web-page.ts
+++ b/src/shared/generate-web-page.ts
@@ -1,3 +1,10 @@
+/**
+ * Opens a new browser tab and writes the given HTML content into it.
+ * Used to display dynamically-generated pages (e.g. PDF-printable views).
+ *
+ * @param content - The full HTML string to write.
+ * @param title   - The document title (default: `"Banglar Bhumi"`).
+ */
 export function generateWebPage(content: string, title: string = "Banglar Bhumi") {
 	const tab = window.open("about:blank", "_blank");
 	if (!tab) {
diff --git a/src/shared/intercept-jquery-ajax.ts b/src/shared/intercept-jquery-ajax.ts
index a77dd44..7e1f54e 100644
--- a/src/shared/intercept-jquery-ajax.ts
+++ b/src/shared/intercept-jquery-ajax.ts
@@ -8,10 +8,15 @@ interface InterceptJqueryEntry {
 const postIntercepts: InterceptJqueryEntry[] = [];
 const getIntercepts: InterceptJqueryEntry[] = [];
 
+/**
+ * On DOMContentLoaded, proxies jQuery's `$.post` and `$.get` so that
+ * registered interceptors are called before the real request.
+ */
 document.addEventListener("DOMContentLoaded", () => {
 	const proxiedPost = $.post;
 	const proxiedGet = $.get;
 
+	/** Proxied `$.post` that invokes registered interceptors before the real call. */
 	$.post = function() {
 		for (const { url, callback } of postIntercepts) {
 			if (arguments[0].endsWith(url)) {
@@ -21,6 +26,7 @@ document.addEventListener("DOMContentLoaded", () => {
 
 		return proxiedPost.apply(this, Array.from(arguments) as any);
 	};
+	/** Proxied `$.get` that invokes registered interceptors before the real call. */
 	$.get = function() {
 		for (const { url, callback } of getIntercepts) {
 			if (arguments[0].endsWith(url)) {
@@ -32,10 +38,24 @@ document.addEventListener("DOMContentLoaded", () => {
 	};
 });
 
+/**
+ * Registers a callback that fires whenever a jQuery POST request matches
+ * the given URL suffix.
+ *
+ * @param url      - The URL suffix to match (checked via `endsWith`).
+ * @param callback - Receives the original `arguments` from `$.post`.
+ */
 export function interceptPost(url: string, callback: InterceptJqueryAjaxCallback) {
 	postIntercepts.push({ url, callback });
 };
 
+/**
+ * Registers a callback that fires whenever a jQuery GET request matches
+ * the given URL suffix.
+ *
+ * @param url      - The URL suffix to match (checked via `endsWith`).
+ * @param callback - Receives the original `arguments` from `$.get`.
+ */
 export function interceptGet(url: string, callback: InterceptJqueryAjaxCallback) {
 	getIntercepts.push({ url, callback });
 };
diff --git a/src/shared/modify-dom.ts b/src/shared/modify-dom.ts
index 22b8e8e..b268ae2 100644
--- a/src/shared/modify-dom.ts
+++ b/src/shared/modify-dom.ts
@@ -10,6 +10,11 @@ type DOMModificationRules = (DOMModificaitonRule | null)[];
 let domModificationRules: DOMModificationRules = [];
 let domModificationFinishedCount = 0;
 
+/**
+ * Runs whenever the DOM mutates.  Iterates over pending modification
+ * rules; when the selector matches, the element's innerHTML and
+ * attributes are updated and the rule is marked as complete.
+ */
 observeDOM(() => {
 	for (let i = 0; i < domModificationRules.length; i++) {
 		if (domModificationRules[i]) {
@@ -45,6 +50,15 @@ observeDOM(() => {
 	return false;
 });
 
+/**
+ * Registers one or more DOM modification rules.  Each rule is a tuple of
+ * `[selector, attributeMap]`.  When an element matching the selector is
+ * found, its `innerHTML` is replaced (if `attributeMap.innerHTML` is set)
+ * and all other entries in the map are applied as `setAttribute` calls
+ * (or `removeAttribute` when the value is `null`).
+ *
+ * @param modificationRules - Array of `[selector, attributes]` rules.
+ */
 export function modifyDOM(modificationRules: DOMModificationRules) {
 	domModificationRules = domModificationRules.concat(modificationRules);
 };
diff --git a/src/shared/observe-dom.ts b/src/shared/observe-dom.ts
index e82ce1e..90a52ff 100644
--- a/src/shared/observe-dom.ts
+++ b/src/shared/observe-dom.ts
@@ -3,6 +3,12 @@ type ObserveDOMCallback = () => boolean;
 let callbacks: (ObserveDOMCallback | null)[] = [];
 let callbacksCalledCount = 0;
 
+/**
+ * Starts a MutationObserver on the document that invokes each
+ * registered callback.  A callback should return `true` when it
+ * has completed its work; once all callbacks are done the observer
+ * disconnects.
+ */
 const observer = new MutationObserver(() => {
 	for (let i = 0; i < callbacks.length; i++) {
 		const callback = callbacks[i];
@@ -24,6 +30,14 @@ observer.observe(document, {
 	subtree: true
 });
 
+/**
+ * Registers a callback to run on DOM mutations.
+ * The callback is invoked on each mutation tick and should return `true`
+ * when its work is finished.  When all callbacks have completed the
+ * observer stops.
+ *
+ * @param callback - Function that returns `true` when done.
+ */
 export function observeDOM(callback: ObserveDOMCallback) {
 	callbacks.push(callback);
 };
diff --git a/src/shared/script-injector.ts b/src/shared/script-injector.ts
index 697c8d6..16cb17c 100644
--- a/src/shared/script-injector.ts
+++ b/src/shared/script-injector.ts
@@ -2,6 +2,15 @@ type DataType = {
 	[key: string]: string
 };
 
+/**
+ * Injects a `<script>` element into the document head (or `<html>`) with
+ * the given `src` pointing to an extension resource.  Optional key/value
+ * data is attached as `data-*` attributes so the injected script can
+ * read them via `document.currentScript`.
+ *
+ * @param src  - The extension-relative script path.
+ * @param data - Optional key/value pairs to set as `data-*` attributes.
+ */
 export function injectScriptHead(src: string, data: DataType = {}) {
 	const s = document.createElement("script") as HTMLScriptElement;
 	s.src = chrome.runtime.getURL(src);
diff --git a/src/shared/styling.ts b/src/shared/styling.ts
index 759fecb..b19ace4 100644
--- a/src/shared/styling.ts
+++ b/src/shared/styling.ts
@@ -1,3 +1,10 @@
+/**
+ * Applies a set of inline CSS styles to every element matching the
+ * given CSS selector.
+ *
+ * @param selector - CSS selector string.
+ * @param styles   - A map of CSS property names to values.
+ */
 export function styles(selector: string, styles: Record<string, string>) {
 	const  elements = Array.from(document.querySelectorAll(selector)) as HTMLElement[];