From 8220c622333a2ce7af60f0ba4703e6aed4fefbb6 Mon Sep 17 00:00:00 2001
From: Starbeamrainbowlabs <sbrl@starbeamrainbowlabs.com>
Date: Sat, 30 Apr 2022 15:03:51 +0100
Subject: [PATCH] comment ask_* functions properly

Ref
https://starbeamrainbowlabs.com/blog/article.php?article=posts/499-whiptail.html
---
 src/run.sh | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/src/run.sh b/src/run.sh
index 52ae24a..d2d29b3 100755
--- a/src/run.sh
+++ b/src/run.sh
@@ -46,12 +46,20 @@ fi
 
 ###############################################################################
 
+# Asks the user a yes/no question.
+# $1	The question to ask the user.
+# Returns 0 if the answer was yes, or 1 if the answer was no.
 ask_yesno() {
 	local question="$1";
 	
 	whiptail --title "Step ${step_current} / ${step_max}" --yesno "${question}" 40 8;
 	return "$?"; # Not actually needed, but best to be explicit
 }
+# Asks the user for a string of text.
+# $1	The window title.
+# $2	The question to ask.
+# $3	The default text value.
+# Returns the answer as a string on the standard output.
 ask_text() {
 	local title="$1";
 	local question="$2";
@@ -59,6 +67,12 @@ ask_text() {
 	whiptail --title "${title}" --inputbox "${question}" 10 40 "${default_text}" 3>&1 1>&2 2>&3;
 	return "$?"; # Not actually needed, but best to be explicit
 }
+
+# Asks the user for a password.
+# $1	The window title.
+# $2	The question to ask.
+# $3	The default text value.
+# Returns the answer as a string on the standard output.
 ask_password() {
 	local title="$1";
 	local question="$2";
@@ -66,6 +80,10 @@ ask_password() {
 	whiptail --title "${title}" --passwordbox "${question}" 10 40 "${default_text}" 3>&1 1>&2 2>&3;
 	return "$?"; # Not actually needed, but best to be explicit
 }
+# Asks the user to choose at most 1 item from a list of items.
+# $1		The window title.
+# $2..$n	The items that the user must choose between.
+# Returns the chosen item as a string on the standard output.
 ask_multichoice() {
 	local title="$1"; shift;
 	local args=();