Fixed wording of some documentation, added missing options

Added documentation of the state_file cache options as well as a few
comments. Also fixed some error messages to be more clear.

README.md

@@ -237,9 +237,14 @@ The `haproxy` section of the config file has the following options:
 * `extra_sections`: additional, manually-configured `frontend`, `backend`, or `listen` stanzas
 * `bind_address`: force HAProxy to listen on this address (default is localhost)
 * `shared_frontend`: (OPTIONAL) additional lines passed to the HAProxy config used to configure a shared HTTP frontend (see below)
-
-* `restart_interval` (default: 2): number of seconds to wait between restarting haproxy/
-* `restart_jitter` (default: 0.0): percentage, expressed as a float, of jitter to multiply the `restart_interval` by when determining the next restart time. Use this to help prevent healthcheck storms when HAProxy restarts.
+* `restart_interval`: number of seconds to wait between restarts of haproxy (default: 2)
+* `restart_jitter`: percentage, expressed as a float, of jitter to multiply the `restart_interval` by when determining the next
+  restart time. Use this to help prevent healthcheck storms when HAProxy restarts. (default: 0.0)
+* `state_file_path`: full path on disk (e.g. /tmp/synapse/state.json) for caching haproxy state between reloads.
+  If provided, synapse will store recently seen backends at this location and can "remember" backends across both synapse and
+  HAProxy restarts. Any backends that are "down" in the reporter but listed in the cache will be put into HAProxy disabled (default: nil)
+* `state_file_ttl`: the number of seconds that backends should be kept in the state file cache.
+  This only applies if `state_file_path` is provided (default: 86400)
 
 Note that a non-default `bind_address` can be dangerous.
 If you configure an `address:port` combination that is already in use on the system, haproxy will fail to start.

lib/synapse/service_watcher/base.rb

@@ -114,12 +114,13 @@ def set_backends(new_backends)
         if @default_servers.empty?
           if @use_previous_backends
             # Discard this update
-            log.warn "synapse: no default servers for service #{@name};" \
-              "  using previous backends: #{@backends.inspect}"
+            log.warn "synapse: no backends for service #{@name} and no default" \
+              " servers for service #{@name}; using previous backends: #{@backends.inspect}"
             return false
           else
-            log.warn "synapse: no default servers for service #{@name} and" \
-              " 'use_previous_backends' is disabled; dropping all backends"
+            log.warn "synapse: no backends for service #{@name}, no default" \
+              " servers for service #{@name} and 'use_previous_backends' is disabled;" \
+              " dropping all backends"
             @backends.clear
           end
         else

lib/synapse/service_watcher/zookeeper.rb

@@ -27,6 +27,8 @@ def stop
     end
 
     def ping?
+      # @zk being nil implies no session *or* a lost session, do not remove
+      # the check on @zk being truthy
       @zk && @zk.connected?
     end