add comments to the new get_default_hostname etc. functions, and simplify the logic in the Vagrantfile and start.sh so that we always call into the same two functions

Vagrantfile

@@ -18,7 +18,7 @@ Vagrant.configure("2") do |config|
 	# machine figure out its own public IP and it'll take a
 	# subdomain on our justtesting.email domain so we can get
 	# started quickly.
-    export PUBLIC_IP=auto-web
+    export PUBLIC_IP=auto
     export PUBLIC_HOSTNAME=auto-easy
     export CSR_COUNTRY=US
 

setup/functions.sh

@@ -20,30 +20,47 @@ function apt_install {
 }
 
 function get_default_hostname {
+	# Guess the machine's hostname. It should be a fully qualified
+	# domain name suitable for DNS. None of these calls may provide
+	# the right value, but it's the best guess we can make.
 	set -- $(hostname --fqdn      2>/dev/null ||
                  hostname --all-fqdns 2>/dev/null ||
                  hostname             2>/dev/null)
-	printf '%s\n' "$1"
+	printf '%s\n' "$1" # return this value
 }
 
 function get_default_publicip {
-	get_publicip_from_web_service || get_publicip_from_dns
+	# Get the machine's public IP address. The machine might have
+	# an IP on a private network, but the IP address that we put
+	# into DNS must be one on the public Internet. Try a public
+	# API, but if that fails (maybe we don't have Internet access
+	# right now) then use the IP address that this machine knows
+	# itself as.
+	get_publicip_from_web_service || get_publicip_fallback
 }
 
 function get_publicip_from_web_service {
+	# This seems to be the most reliable way to determine the
+	# machine's public IP address: asking a very nice web API
+	# for how they see us. Thanks go out to icanhazip.com.
 	curl --fail --silent icanhazip.com 2>/dev/null
 }
 
-function get_publicip_from_dns {
+function get_publicip_fallback {
+	# Return the IP address that this machine knows itself as.
+	# It certainly may not be the IP address that this machine
+	# operates as on the public Internet. The machine might
+	# have multiple addresses if it has multiple network adapters.
 	set -- $(hostname --ip-address       2>/dev/null) \
 	       $(hostname --all-ip-addresses 2>/dev/null)
 	while (( $# )) && is_loopback_ip "$1"; do
 		shift
 	done
-	printf '%s\n' "$1"
+	printf '%s\n' "$1" # return this value
 }
 
 function is_loopback_ip {
+	# helper for get_publicip_fallback
 	[[ "$1" == 127.* ]]
 }
 

setup/start.sh

@@ -71,18 +71,13 @@ fi
 
 # Automatic configuration, e.g. as used in our Vagrant configuration.
 if [ "$PUBLIC_IP" == "auto" ]; then
-	# Assume `get_publicip_from_dns` gives the correct public IP address for the machine.
-	PUBLIC_IP=`get_publicip_from_dns`
-	echo "IP Address: $PUBLIC_IP"
-fi
-if [ "$PUBLIC_IP" == "auto-web" ]; then
 	# Use a public API to get our public IP address.
-	PUBLIC_IP=`get_publicip_from_web_service`
+	PUBLIC_IP=`get_default_publicip`
 	echo "IP Address: $PUBLIC_IP"
 fi
 if [ "$PUBLIC_HOSTNAME" == "auto-easy" ]; then
 	# Generate a probably-unique subdomain under our justtesting.email domain.
-	PUBLIC_HOSTNAME=m`get_publicip_from_dns | sha1sum | cut -c1-5`.justtesting.email
+	PUBLIC_HOSTNAME=m`get_default_publicip | sha1sum | cut -c1-5`.justtesting.email
 	echo "Public Hostname: $PUBLIC_HOSTNAME"
 fi