From b4c1ccef76145901de8fe04ed87748130c1e0eaf Mon Sep 17 00:00:00 2001
From: Maarten van Gompel <proycon@anaproy.nl>
Date: Mon, 19 Jul 2021 20:00:51 +0200
Subject: [PATCH] adding some comments to screenlock to make it easier to
 understand

This merely adds some comments to make sure the code is
easier to understand.

Signed-off-by: Stacy Harper <contact@stacyharper.net>
---
 scripts/core/sxmo_screenlock.sh | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/scripts/core/sxmo_screenlock.sh b/scripts/core/sxmo_screenlock.sh
index ed9cffe..71fc5a1 100755
--- a/scripts/core/sxmo_screenlock.sh
+++ b/scripts/core/sxmo_screenlock.sh
@@ -20,6 +20,7 @@ OLD_MODEM_WAKECOUNT="$XDG_RUNTIME_DIR/wakeup.modem.count"
 OLD_POWER_WAKECOUNT="$XDG_RUNTIME_DIR/wakeup.power.count"
 
 saveAllEventCounts() {
+	#these help us determine the reason of the next wakeup
 	cat "$WAKEUPRTC" > "$OLD_RTC_WAKECOUNT"
 	cat "$MODEMUPRTC" > "$OLD_MODEM_WAKECOUNT"
 	cat "$POWERRTC" > "$OLD_POWER_WAKECOUNT"
@@ -27,6 +28,7 @@ saveAllEventCounts() {
 }
 
 whichWake() {
+    #attempt to find the reason why we woke up:
 	if [ "$(cat "$POWERRTC")" -gt "$(cat "$OLD_POWER_WAKECOUNT")" ] ; then
 		echo "usb power"
 	elif [ "$(cat "$MODEMUPRTC")" -gt "$(cat "$OLD_MODEM_WAKECOUNT")" ] ; then
@@ -40,18 +42,20 @@ whichWake() {
 }
 
 getCurState() {
+	#get the current state of the lock
 	if xinput list-props "$TOUCH_POINTER_ID" | grep "Device Enabled" | grep -q "0$"; then
 		if xset q | grep -q "Off: 3"; then
-			echo "off"
+			echo "off" #locked, and screen off
 		else
-			echo "lock"
+			echo "lock" #locked, but screen on
 		fi
 	else
-		echo "unlock"
+		echo "unlock" #normal mode, not locked
 	fi
 }
 
 updateLed() {
+	#set the LED to reflect the current lock state
 	case "$(getCurState)" in
 		"off")
 			echo 1 > "$REDLED_PATH"
@@ -74,12 +78,15 @@ if [ "$1" != "getCurState" ]; then
 fi
 
 if [ "$1" = "lock" ] ; then
+	#locked state with screen on
+
 	# always echo last state first so that user can use it in their hooks
 	# TODO: Document LASTSTATE
 	getCurState > "$LASTSTATE"
 	# Do we want this hook after disabling all the input devices so users can enable certain devices?
 	sxmo_hooks.sh lock
 
+	#turn screen on
 	xset dpms 0 0 0
 	xset dpms force on
 
@@ -94,11 +101,16 @@ if [ "$1" = "lock" ] ; then
 	updateLed
 	exit 0
 elif [ "$1" = "unlock" ] ; then
+	#normal unlocked state, screen on
+
 	getCurState > "$LASTSTATE"
 	sxmo_hooks.sh unlock
 
+	#turn screen back on
 	xset dpms 0 0 0
 	xset dpms force on
+
+	#start responding to touch input again
 	xinput enable "$TOUCH_POINTER_ID"
 	sxmo_hooks.sh lisgdstart &
 	echo 16000 > "$NETWORKRTCSCAN"
@@ -106,13 +118,18 @@ elif [ "$1" = "unlock" ] ; then
 	updateLed
 	exit 0
 elif [ "$1" = "off" ] ; then
+	#locked state with screen off
+
 	getCurState > "$LASTSTATE"
 	# TODO: document this hook
 	sxmo_hooks.sh screenoff
 
+	#turn screen off, but have dpms temporarily enable
+	#the screen when a button is pressed
 	xset dpms 0 0 3
 	xset dpms force off
-	# stop responding to input
+
+	# stop responding to touch input
 	xinput disable "$TOUCH_POINTER_ID"
 	killall lisgd
 
@@ -129,6 +146,7 @@ elif [ "$1" = "crust" ] ; then
 
 	sxmo_hooks.sh presuspend
 
+	#turn screen off
 	xset dpms force off
 	suspend_time="$(($(mnc)-10))"
 
@@ -137,7 +155,9 @@ elif [ "$1" = "crust" ] ; then
 		suspend_time="$YEARS8_TO_SEC"
 	fi
 	if [ "$suspend_time" -gt 0 ]; then
+		#The actual suspension to crust happens here, mediated by rtcwake
 		rtcwake -m mem -s "$suspend_time"
+		#We woke up again
 		UNSUSPENDREASON=$(whichWake)
 	else
 		UNSUSPENDREASON=rtc # we fake the crust for those seconds
@@ -152,6 +172,7 @@ elif [ "$1" = "crust" ] ; then
 	echo "sxmo_screenlock: woke up from crust (reason=$UNSUSPENDREASON) ($d)" >&2
 
 	if [ "$UNSUSPENDREASON" != "rtc" ]; then
+		#turn screen on only when we didn't wake up from an rtc event
 		xset dpms force on
 	fi