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

Adding documentation comments

1 files changed, 26 insertions, 10 deletions

diff --git a/src/shared/modify-dom.ts b/src/shared/modify-dom.ts
index 22b8e8e..41e8730 100644
--- a/src/shared/modify-dom.ts
+++ b/src/shared/modify-dom.ts
@@ -2,7 +2,7 @@ import { observeDOM } from "@/shared/observe-dom";
 
 type DOMReplacements = {
 	innerHTML?: string;
-	[key: string]: string | undefined | null;
+	[key: string]: string | undefined | null
 };
 type DOMModificaitonRule = readonly [string, DOMReplacements];
 type DOMModificationRules = (DOMModificaitonRule | null)[];
@@ -10,25 +10,32 @@ 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]) {
-			const element = document.querySelector(domModificationRules[i]![0]) as HTMLElement | null;
+		const rule = domModificationRules[i];
+		if (rule?.[0]) {
+			const element = document.querySelector(rule[0]);
 
 			if (element) {
-				const attributes = domModificationRules[i]![1];
+				const attributes = rule[1];
 
 				if (attributes.innerHTML) {
-					element.innerHTML = attributes.innerHTML as string;
+					element.innerHTML = attributes.innerHTML;
 				}
 
 				delete attributes.innerHTML;
 
-				for (const attribute in attributes) {
-					if (attributes[attribute] === null) {
-						element.removeAttribute(attribute);
+				for (const attributeName in attributes) {
+					const attribute = attributes[attributeName];
+					if (attribute) {
+						element.setAttribute(attributeName, attribute);
 					} else {
-						element.setAttribute(attribute, attributes[attribute] as string);
+						element.removeAttribute(attributeName);
 					}
 				}
 
@@ -45,6 +52,15 @@ observeDOM(() => {
 	return false;
 });
 
-export function modifyDOM(modificationRules: DOMModificationRules) {
+/**
+ * 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): void {
 	domModificationRules = domModificationRules.concat(modificationRules);
 };