comments for all lines and small formatting changes

advanced/Scripts/piholeDebug.sh

@@ -47,10 +47,14 @@ else
 fi
 
 echo_succes_or_fail() {
+  # Set the first argument passed to tihs function as a named variable for better readability
   local message="${1}"
+  # If the command was successful (a zero),
   if [ $? -eq 0 ]; then
+    # show success
     echo -e "    ${TICK} ${message}"
   else
+    # Otherwise, show a error
     echo -e "    ${CROSS} ${message}"
   fi
 }
@@ -59,17 +63,20 @@ initiate_debug() {
   # Clear the screen so the debug log is readable
   clear
   echo -e "${COL_LIGHT_PURPLE}*** [ INITIALIZING ]${COL_NC}"
+  # Timestamp the start of the log
   echo -e "    ${INFO} $(date "+%Y-%m-%d:%H:%M:%S") debug log has been initiated."
 }
 
 # This is a function for visually displaying the curent test that is being run.
 # Accepts one variable: the name of what is being diagnosed
+# Colors do not show in the dasboard, but the icons do: [i], [✓], and [✗]
 echo_current_diagnostic() {
   # Colors are used for visually distinguishing each test in the output
   echo -e "\n${COL_LIGHT_PURPLE}*** [ DIAGNOSING ]:${COL_NC} ${1}"
 }
 
 if_file_exists() {
+  # Set the first argument passed to tihs function as a named variable for better readability
   local file_to_test="${1}"
   # If the file is readable
   if [[ -r "${file_to_test}" ]]; then
@@ -88,13 +95,17 @@ get_distro_attributes() {
   # but we'll keep it within the function for better unit testing
   IFS=$'\r\n' command eval 'distro_info=( $(cat /etc/*release) )'
 
+  # Set a named variable for better readability
   local distro_attribute
+  # For each line found in an /etc/*release file,
   for distro_attribute in "${distro_info[@]}"; do
-    # Display the information with the ${INFO} icon (we need just the OS PRETTY_NAME)
+    # display the information with the ${INFO} icon
     pretty_name_key=$(echo "${distro_attribute}" | grep "PRETTY_NAME" | cut -d '=' -f1)
+    # we need just the OS PRETTY_NAME, so print it when we find it
     if [[ "${pretty_name_key}" == "PRETTY_NAME" ]]; then
       PRETTY_NAME=$(echo "${distro_attribute}" | grep "PRETTY_NAME" | cut -d '=' -f2- | tr -d '"')
       echo "    ${INFO} ${PRETTY_NAME}"
+      # Otherwise, do nothing
     else
       :
     fi
@@ -104,6 +115,8 @@ get_distro_attributes() {
 }
 
 diagnose_operating_system() {
+  local faq_url="https://discourse.pi-hole.net/t/hardware-software-requirements/273"
+  local error_msg="Distribution unknown -- most likely you are on an unsupported platform and may run into issues."
   # Display the current test that is running
   echo_current_diagnostic "Operating system"
 
@@ -111,20 +124,24 @@ diagnose_operating_system() {
   if_file_exists /etc/*release && \
     # display the attributes to the user
     get_distro_attributes || \
-    # If it doesn't exist, it's not a system we currently support
-    echo -e "   ${CROSS} ${COL_LIGHT_RED}Distribution unknown -- most likely you are on an unsupported platform and may run into issues.${COL_NC}
-        ${INFO} ${COL_LIGHT_RED}Please see${COL_NC}: ${COL_CYAN}https://discourse.pi-hole.net/t/hardware-software-requirements/273${COL_NC}"
+    # If it doesn't exist, it's not a system we currently support and link to FAQ
+    echo -e "    ${CROSS} ${COL_LIGHT_RED}${error_msg}${COL_NC}
+         ${INFO} ${COL_LIGHT_RED}Please see${COL_NC}: ${COL_CYAN}${faq_url}${COL_NC}"
 }
 
 parse_file() {
+  # Set the first argument passed to tihs function as a named variable for better readability
   local filename="${1}"
+  # Put the current Internal Field Separator into another variable so it can be restored later
   OLD_IFS="$IFS"
+  # Get the lines that are in the file(s) and store them in an array for parsing later
   IFS=$'\r\n' command eval 'file_info=( $(cat "${filename}") )'
 
+  # Set a named variable for better readability
   local file_lines
+  # For each lin in the file,
   for file_lines in "${file_info[@]}"; do
-    # Display the information with the ${INFO} icon
-    # No need to show the support URLs so they are grepped out
+    # display the information with the ${INFO} icon
     echo "       ${INFO} ${file_lines}"
   done
   # Set the IFS back to what it was
@@ -148,30 +165,45 @@ diagnose_setup_variables() {
     parse_file "${VARSFILE}"
 }
 
+# This function can check a directory exists
+# Pi-hole has files in several places, so we will reuse this function
 dir_check() {
+  # Set the first argument passed to tihs function as a named variable for better readability
   local directory="${1}"
+  # Display the current test that is running
   echo_current_diagnostic "contents of ${directory}"
+  # For each file in the directory,
   for filename in "${directory}"*; do
+    # check if exists first; if it does,
     if_file_exists "${filename}" && \
+    # show a success message
     echo_succes_or_fail "Files detected" || \
+    # Otherwise, show an error
     echo_succes_or_fail "directory does not exist"
   done
 }
 
 list_files_in_dir() {
+  # Set the first argument passed to tihs function as a named variable for better readability
   local dir_to_parse="${1}"
+  # Set another local variable for better readability
   local filename
+  # Store the files found in an array
   files_found=( $(ls "${dir_to_parse}") )
+  # For each file in the arry,
   for each_file in "${files_found[@]}"; do
-    # Display the information with the ${INFO} icon
+    # display the information with the ${INFO} icon
     echo "       ${INFO} ${each_file}"
   done
 
 }
 
 check_dnsmasq_d() {
+  # Set a local variable for better readability
   local directory=/etc/dnsmasq.d
+  # Check if the directory exists
   dir_check "${directory}"
+  # if it does, list the files in it
   list_files_in_dir "${directory}"
 }