From 600c337b1cdc884aebf59083eb57b178b43441ce Mon Sep 17 00:00:00 2001
From: Arpit Chakladar <arpitchakladar+git@gmail.com>
Date: Mon, 13 Jul 2026 11:35:08 +0530
Subject: docs: added some documentation comments to all functions

---
 src/scripts/captcha/application-receipt.ts        |  5 +++++
 src/scripts/captcha/know-your-property.ts         |  5 +++++
 src/scripts/functionality/mutation-application.ts |  6 ++++++
 src/scripts/functionality/sheet-map/index.ts      | 26 +++++++++++++++++++++++
 src/scripts/functionality/view-khatian/index.ts   | 17 +++++++++++++++
 src/scripts/login/index.ts                        | 15 +++++++++++++
 src/scripts/stop-blocking.ts                      |  8 +++++++
 7 files changed, 82 insertions(+)

(limited to 'src/scripts')

diff --git a/src/scripts/captcha/application-receipt.ts b/src/scripts/captcha/application-receipt.ts
index 595195e..c5bb657 100644
--- a/src/scripts/captcha/application-receipt.ts
+++ b/src/scripts/captcha/application-receipt.ts
@@ -1,3 +1,8 @@
+/**
+ * Hides the CAPTCHA section on the application-receipt page and
+ * stubs the form validation so the user can proceed without
+ * solving a CAPTCHA.
+ */
 document.addEventListener("DOMContentLoaded", () => {
 	$("#werter > div > form > div:nth-child(4)").hide();
 	(window as any).validateForm = () => true;
diff --git a/src/scripts/captcha/know-your-property.ts b/src/scripts/captcha/know-your-property.ts
index 6e11a3f..3abdf08 100644
--- a/src/scripts/captcha/know-your-property.ts
+++ b/src/scripts/captcha/know-your-property.ts
@@ -1,3 +1,8 @@
+/**
+ * Hides the CAPTCHA section on the Know-Your-Property page and
+ * stubs the captcha validation so the user can proceed without
+ * solving a CAPTCHA.
+ */
 document.addEventListener("DOMContentLoaded", () => {
 	$("#khatianPlotDiv > div:nth-child(6) > div").hide();
 	(window as any).validateCaptcha = () => true;
diff --git a/src/scripts/functionality/mutation-application.ts b/src/scripts/functionality/mutation-application.ts
index 96aec8a..c067b25 100644
--- a/src/scripts/functionality/mutation-application.ts
+++ b/src/scripts/functionality/mutation-application.ts
@@ -3,6 +3,12 @@ import { observeDOM } from "@/shared/observe-dom";
 
 const sanghaFacilitationCentreBannerUrl = "$l{ /assets/sangha-facilitation-centre-banner.jpg }l$";
 
+/**
+ * On the Mutation Application form, removes the form action (to prevent
+ * the default server-side submit) and attaches a custom click handler
+ * that fetches the declaration PDF, overlays a banner image and date
+ * stamp on the last page, then triggers a download.
+ */
 document.addEventListener("DOMContentLoaded", () => {
 	observeDOM(() => {
 		const formElement = $("#form_MutationApplication > div > div:nth-child(14) > div.col-sm-2.btreset > form");
diff --git a/src/scripts/functionality/sheet-map/index.ts b/src/scripts/functionality/sheet-map/index.ts
index 71228fe..3d566c2 100644
--- a/src/scripts/functionality/sheet-map/index.ts
+++ b/src/scripts/functionality/sheet-map/index.ts
@@ -23,6 +23,13 @@ let plotNumberLabelTextElements = "";
 
 document.body.appendChild(plotInformation);
 
+/**
+ * Creates a header toolbar button and appends it to the page header.
+ * The button starts hidden and is shown when data is ready.
+ *
+ * @param text - The button label text.
+ * @returns The created button element.
+ */
 const createHeaderButton = (text: string) => {
 	const buttonContainer = document.createElement("td");
 	const button = document.createElement("button");
@@ -33,6 +40,12 @@ const createHeaderButton = (text: string) => {
 	return button;
 };
 
+/**
+ * Displays the area and plot number for the given polygon in a floating
+ * info panel, or shows "0.000" / empty if no polygon is selected.
+ *
+ * @param plotPolygon - The selected plot's data, or `null`/`undefined` to clear.
+ */
 const setPlotInformation = (plotPolygon: PlotPolygon | null | undefined = null) => {
 	plotInformation.innerHTML = plotPolygon ? getPlotInformationElement({
 		area: (plotPolygon.plotArea/1000).toFixed(3),
@@ -43,7 +56,14 @@ const setPlotInformation = (plotPolygon: PlotPolygon | null | undefined = null)
 	});
 };
 
+/**
+ * Opens a new window with a printable PDF view of the map, optionally
+ * including plot-number labels.
+ *
+ * @param labelPoints - Whether to include plot number text labels.
+ */
 const downloadPDF = (labelPoints: boolean = true) => {
+	/** Extracts a detail value (district/block/mouza) from the header table by column index. */
 	const _getMapDetail = (i: number) => {
 		const detail = document.querySelector(`#headerTable > tbody > tr > td:nth-child(${i})`)!
 			.innerHTML
@@ -147,6 +167,12 @@ setPlotInformation();
 		}
 	}, 300);
 
+	/**
+	 * Highlights the clicked plot on the SVG map and shows its
+	 * information in the info panel.
+	 *
+	 * @param e - The mouse click event.
+	 */
 	const handlePlotClick = (e: MouseEvent) => {
 		document.querySelectorAll("path").forEach(e => {
 			e.setAttribute("fill", "#ffcc66");
diff --git a/src/scripts/functionality/view-khatian/index.ts b/src/scripts/functionality/view-khatian/index.ts
index 93d03cf..34e6765 100644
--- a/src/scripts/functionality/view-khatian/index.ts
+++ b/src/scripts/functionality/view-khatian/index.ts
@@ -14,6 +14,12 @@ const styles = Array.from(submitButtonElementComputedStyles)
 		""
 	);
 
+/**
+ * Reads the currently selected text from a `<select>` element.
+ *
+ * @param selector - CSS selector for the select element.
+ * @returns The text of the selected option.
+ */
 const getValueOfSelectElement = (selector: string) => {
 	const element = document.querySelector<HTMLSelectElement>(selector)!;
 	return element.options[element.selectedIndex].text;
@@ -21,6 +27,10 @@ const getValueOfSelectElement = (selector: string) => {
 
 let isPlotInformation: boolean | null = null;
 
+/**
+ * Opens a new window with a printable PDF view of the current khatian
+ * or plot details, including district/block/mouza info.
+ */
 const downloadInformationPDF = () => {
 	generateWebPage(
 		getDownloadInformationPDFPageContent({
@@ -36,6 +46,13 @@ const downloadInformationPDF = () => {
 	);
 };
 
+/**
+ * Intercepts the success callback of a jQuery AJAX call.  When a valid
+ * details table is returned, it inserts a "Download PDF" button;
+ * otherwise it removes an existing button.
+ *
+ * @param args - The `arguments` object from the intercepted `$.post` call.
+ */
 const showDownloadButton = (args: any) => {
 	if (isPlotInformation !== null) {
 		const callback = args[2];
diff --git a/src/scripts/login/index.ts b/src/scripts/login/index.ts
index bed05f9..dcf43e3 100644
--- a/src/scripts/login/index.ts
+++ b/src/scripts/login/index.ts
@@ -1,18 +1,33 @@
 import { interceptPost, interceptGet } from "@/shared/intercept-jquery-ajax";
 
+/**
+ * Pre-processes a CAPTCHA image on a canvas by removing grayish
+ * background noise while preserving dark pixels, producing a clean
+ * binary image suitable for OCR.
+ *
+ * @param ctx    - The 2D rendering context of the canvas.
+ * @param width  - Canvas width in pixels.
+ * @param height - Canvas height in pixels.
+ */
 function prepareCaptcha(ctx: CanvasRenderingContext2D, width: number, height: number) {
 	const imgData = ctx.getImageData(0, 0, width, height);
 	const data = imgData.data;
 	const radius = 1;
 
+	/** Returns true when all three channels are below 50 (very dark). */
 	function isBlack(r: number, g: number, b: number) {
 		return r < 50 && g < 50 && b < 50;
 	}
 
+	/** Returns true when the colour is a mid-range grey (no strong hue). */
 	function isGrayish(r: number, g: number, b: number) {
 		return Math.abs(r - g) < 15 && Math.abs(g - b) < 15 && r > 100 && r < 200;
 	}
 
+	/**
+	 * Checks whether a black pixel exists within `radius` pixels of (x, y).
+	 * Used to preserve dark structures when removing grey noise.
+	 */
 	function hasNearbyBlack(x: number, y: number) {
 		for (let dx = -radius; dx <= radius; dx++) {
 			for (let dy = -radius; dy <= radius; dy++) {
diff --git a/src/scripts/stop-blocking.ts b/src/scripts/stop-blocking.ts
index b8f4783..3fa3de6 100644
--- a/src/scripts/stop-blocking.ts
+++ b/src/scripts/stop-blocking.ts
@@ -1,5 +1,12 @@
+/**
+ * Proxies jQuery's `.bind()` (for the `"cut copy paste"` event) and
+ * `.keydown()` so that the website's copy/paste/right-click blocking
+ * is disabled.  Reverts the prototypes after patching to avoid
+ * interfering with other code.
+ */
 document.addEventListener("DOMContentLoaded", () => {
 	const proxiedBind = $.prototype.bind;
+	/** Proxies jQuery `.bind()` to no-op the `"cut copy paste"` event. */
 	$.prototype.bind = function() {
 		if (arguments[0].trim() === "cut copy paste") {
 			arguments[1] = (_: any) => {};
@@ -9,6 +16,7 @@ document.addEventListener("DOMContentLoaded", () => {
 	}
 
 	const proxiedKeydown = $.prototype.keydown;
+	/** Proxies jQuery `.keydown()` so all key presses are allowed. */
 	$.prototype.keydown = function() {
 		arguments[0] = (_: any) => true;
 
-- 
cgit v1.2.3