Added more comments to JS files; slight refactoring

options.js

@@ -2,9 +2,13 @@
 /* EVENTS */
 /**********/
 
+/*	Triggered when a click is received by the mode selector switch, or by 
+	either of the two labels (“Blacklist” and “Whitelist”).
+	*/
 function modeSelectorInputReceived() {
 	toggleModeSelectorState();
-	window.currentMode = (window.currentMode == "whitelist") ? "blacklist" : "whitelist";
+
+	// Activate the “Reset” and “Save” buttons, since changes have been made.
 	setButtonsActive(true);
 }
 
@@ -12,22 +16,35 @@ function modeSelectorInputReceived() {
 /* HELPERS */
 /***********/
 
+/*	Toggles all UI state associated with mode selection. Called on input to
+	the mode selector (see modeSelectorInputReceived()), OR when changes are 
+	reset (see resetChanges()).
+	*/
 function toggleModeSelectorState(newMode) {
+	/*	Update state of the checkbox itself, and the container div. */
 	let container = document.querySelector(".mode-select-container");
 	let checkbox = document.querySelector("input#whitelist-mode");
 	newMode = newMode || (container.classList.contains("whitelist") ? "blacklist" : "whitelist");
-
 	container.classList.toggle("whitelist", (newMode == "whitelist"));
 	checkbox.checked = (newMode == "whitelist");
+
+	/*	Enable both spans (the “Blacklist” and “Whitelist” labels, then disable 
+		just the label associated with the now-enabled mode. */
 	container.querySelectorAll("span").forEach(span => {
 		span.classList.toggle("disabled", false);
 	});
 	document.querySelector(`.${newMode}-mode-label`).classList.toggle("disabled", true);
 
+	/*	In whitelist mode, the matching patterns textarea must be disabled,
+		since the matching patterns list is treated as containing only the 
+		single pattern “.*”. An overlay is shown, to indicate this. */
 	document.querySelector("div#matchingPatterns").classList.toggle("disabled", (newMode == "whitelist"));
 	document.querySelector("div#matchingPatterns textarea").disabled = (newMode == "whitelist");
 }
 
+/*	Saves the entered state in storage.
+	De-activate the “Reset” and “Save” buttons.
+	*/
 function saveChanges() {
 	let matchingPatterns = document.querySelector("#matchingPatterns textarea").value;
 	let exclusionPatterns = document.querySelector("#exclusionPatterns textarea").value;
@@ -39,28 +56,46 @@ function saveChanges() {
 	}, () => { setButtonsActive(false); });
 }
 
-function resetChanges() {
+/*	Retrieves the saved state from storage and reset the UI to reflect it, 
+	discarding the user’s changes.
+	*/
+function resetChanges(callback) {
 	chrome.storage.sync.get([ "matchingPatterns", "exclusionPatterns", "mode" ], (result) => {
-		document.querySelector("#matchingPatterns textarea").value = result.matchingPatterns || "";
-		document.querySelector("#exclusionPatterns textarea").value = result.exclusionPatterns || "";
-		window.currentMode = result.mode || "blacklist";
+		AKS.matchingPatterns = result.matchingPatterns || "";
+		AKS.exclusionPatterns = result.exclusionPatterns || ""
+		AKS.mode = result.mode || "blacklist";
+
+		document.querySelector("#matchingPatterns textarea").value = AKS.matchingPatterns;
+		document.querySelector("#exclusionPatterns textarea").value = AKS.exclusionPatterns;
 
-		toggleModeSelectorState(window.currentMode);
+		toggleModeSelectorState(AKS.mode);
+
+		// De-activate the “Reset” and “Save” buttons.
 		setButtonsActive(false);
 
 		// Expand all textareas.
 		document.querySelectorAll("textarea").forEach(textarea => {
 			expandTextarea(textarea);
 		});
+
+		// Trigger provided callback, if any.
+		if (callback) callback();
 	});
 }
 
+/*	Activates or de-activates the “Reset” and “Save” buttons. Called when 
+	changes are made (to activate) or when changes are saved or reset (to 
+	de-activate).
+	*/
 function setButtonsActive(active) {
 	document.querySelectorAll("button").forEach(button => {
 		button.disabled = !active;
 	});
 }
 
+/*	Expands a textarea to show all its contents (up to a maximum height which is
+	set via CSS).
+	*/
 function expandTextarea(textarea) {
 	let totalBorderHeight = 2;
 	if (textarea.clientHeight == textarea.scrollHeight + totalBorderHeight) return;
@@ -75,9 +110,12 @@ function expandTextarea(textarea) {
 /******************/
 
 function initialize() {
-	resetChanges();
-	chrome.storage.sync.get("mode", (result) => {
-		let divToFocus = (result.mode == "whitelist") ? "#exclusionPatterns" : "#matchingPatterns";
+	window.AKS = { };
+
+	/*	Retrieve saved settings from storage, and set all UI elements to their 
+		proper state. Then, focus the first active textarea. */
+	resetChanges(() => {
+		let divToFocus = (AKS.mode == "whitelist") ? "#exclusionPatterns" : "#matchingPatterns";
 		document.querySelector(`${divToFocus} textarea`).focus();
 	});
 

popup.js

@@ -53,6 +53,10 @@ function toggleState() {
 	recalculatePatternEffects();
 }
 
+/*	Given a patterns list (whether matching or exclusion), enables all patterns
+	that match the current page URL, if any. If none are found, adds a new 
+	pattern for the current tab.
+	*/
 function addPatternForCurrentTab(patterns) {
 	/*	First, we see if there are already any existing but commented-out 
 		patterns that match the active tab. If so, we enable them all. */
@@ -80,6 +84,9 @@ function addPatternForCurrentTab(patterns) {
 	patterns.push("");
 }
 
+/*	Given a patterns list (whether matching or exclusion), disables all patterns
+	that match the current page URL.
+	*/
 function disablePatternsForCurrentTab(patterns) {
 	for (var i = 0; i < patterns.length; i++) {
 		if (patterns[i] && AKS.activeTabLocation.match(new RegExp(patterns[i])))
@@ -87,12 +94,18 @@ function disablePatternsForCurrentTab(patterns) {
 	}
 }
 
+/*	Creates a regexp that matches the current page URL. This regexp will match
+	all pages on the same domain.
+	*/
 function regExpForCurrentTab() {
 	let a = document.createElement("A");
 	a.href = AKS.activeTabLocation;
 	return ".*" + a.host.replace(/\./g, "\\.") + ".*";
 }
 
+/*	Recalculates the values of AKS.pageMatched and AKS.pageExcluded, based on
+	the contents of the matching and exclusion patterns lists.
+	*/
 function recalculatePatternEffects() {
 	AKS.pageMatched = false;
 	AKS.pageExcluded = false;
@@ -114,6 +127,14 @@ function recalculatePatternEffects() {
 	}
 }
 
+/*	Updates the values of properties of the AKS object on the basis of the 
+	provided result object. Called after a query to storage (to retrieve the
+	result object).
+
+	Updated properties are: the current mode, the matching and exclusion 
+	patterns lists, and the ‘pageMatched’ and ‘pageExcluded’ properties (which
+	are computed from the patterns lists).
+	*/
 function updateState(result) {
 	AKS.mode = result.mode || "blacklist";
 	AKS.matchingPatterns = (AKS.mode == "whitelist") ?
@@ -127,11 +148,24 @@ function updateState(result) {
 	recalculatePatternEffects();
 }
 
+/*	Updates the state of all UI elements to reflect the current values of the
+	AKS object (see updateState()).
+	*/
 function updateUIState() {
+	// The big button.
 	let mainButton = document.querySelector("button.main-button");
+	// The block containing the mode indicator and the “Killing stickies?” label.
 	let info = document.querySelector(".info");
+	// The “Killing stickies?” label.
 	let statusLabel = document.querySelector(".info .status-display");
+
 	var active, whitelist;
+
+	/*	The extension (and thus the main button) is shown as ‘active’ if:
+		(a) Blacklist mode is active, the current page is matched, and NOT
+			excluded; or,
+		(b) Whitelist mode is active, and the current page is NOT excluded.
+		*/
 	if (AKS.mode == "blacklist") {
 		if (AKS.pageMatched && !AKS.pageExcluded) {
 			active = true;