Add documentation comments to test_server and pick_server functions

zzz_evobackup

@@ -46,8 +46,12 @@ export LANG=C
 ## Force umask
 umask 077
 
+# Call test_server with "HOST:PORT" string
+# It will return with 0 if the server is reachable.
+# It will return with 1 and a message on stderr if not.
 test_server() {
     item=$1
+    # split HOST and PORT from the input string
     host=$(echo "${item}" | cut -d':' -f1)
     port=$(echo "${item}" | cut -d':' -f2)
 
@@ -55,23 +59,32 @@ test_server() {
     ssh -q -o "ConnectTimeout ${SSH_CONNECT_TIMEOUT}" "${host}" -p "${port}" -t "exit"
     # shellcheck disable=SC2181
     if [ $? = 0 ]; then
+        # SSH connection is OK
         return 0
     else
+        # SSH connection failed
         echo "Failed to connect to \`${item}' within ${SSH_CONNECT_TIMEOUT} seconds" >&2
         return 1
     fi
 }
+# Call pick_server with an optional positive integer to get the nth server in the list.
 pick_server() {
-    inc=${1:-0}
+    increment=${1:-0}
     list_length=$(echo "${SERVERS}" | wc -w)
 
-    if [ "${inc}" -ge "${list_length}" ]; then
+    if [ "${increment}" -ge "${list_length}" ]; then
+        # We've reached the end of the list
         echo "No more server available" >&2
         return 1
     fi
 
+    # A salt is useful to randomize the starting point in the list
+    # but stay identical each time it's called for a server (based on hostname).
     salt=$(hostname | cksum | cut -d' ' -f1)
-    item=$(( ($(date +%d) + salt + inc) % list_length ))
+    # Pick an integer between 0 and the length of the SERVERS list
+    # It changes each day
+    item=$(( ($(date +%d) + salt + increment) % list_length ))
+    # cut starts counting fields at 1, not 0.
     field=$(( item + 1 ))
 
     echo "${SERVERS}" | cut -d' ' -f${field}