Fix all READMEs and some other fluff (#788)

middleware/bind/README.md

@@ -1,8 +1,9 @@
 # bind
 
-*bind* overrides the host to which the server should bind. Normally, the listener binds to the
+*bind* overrides the host to which the server should bind.
-wildcard host. However, you may force the listener to bind to another IP instead. This
+
-directive accepts only an address, not a port.
+Normally, the listener binds to the wildcard host. However, you may force the listener to bind to
+another IP instead. This directive accepts only an address, not a port.
 
 ## Syntax
 

middleware/chaos/README.md

@@ -1,6 +1,7 @@
 # chaos
 
 The *chaos* middleware allows CoreDNS to respond to TXT queries in the CH class.
+
 This is useful for retrieving version or author information from the server.
 
 ## Syntax

middleware/debug/README.md

@@ -1,7 +1,7 @@
 # debug
 
-*debug* disables the automatic recovery upon a CoreDNS crash so that you'll get a
+*debug* disables the automatic recovery upon a CoreDNS crash so that you'll get a nice stack trace.
-nice stack trace.
+
 Note that the *errors* middleware (if loaded) will also set a `recover` negating this setting.
 The main use of *debug* is to help testing.
 

middleware/erratic/README.md

@@ -1,11 +1,7 @@
 # erratic
 
 *erratic* is a middleware useful for testing client behavior. It returns a static response to all
-queries, but the responses can be:
+queries, but the responses can be delayed, dropped or truncated.
-
-* delayed by some duration
-* dropped all together
-* the truncated bit can be set
 
 The *erratic* middleware will respond to every A or AAAA query. For any other type it will return
 a SERVFAIL response. The reply for A will return 192.0.2.53 (see RFC 5737), for AAAA it returns

middleware/errors/README.md

@@ -1,7 +1,8 @@
 # errors
 
 *errors* enables error logging.
-TODO: what are errors.
+
+Any errors encountered during the query processing will be printed on standard output.
 
 ## Syntax
 

middleware/hosts/README.md

@@ -1,6 +1,6 @@
 # hosts
 
-*hosts* enables serving zone data from a /etc/hosts style file.
+*hosts* enables serving zone data from a `/etc/hosts` style file.
 
 The hosts middleware is useful for serving zones from a /etc/hosts file. It serves from a preloaded
 file that exists on disk. It checks the file for changes and updates the zones accordingly. This

middleware/loadbalance/README.md

@@ -1,11 +1,11 @@
 # loadbalance
 
 *loadbalance* acts as a round-robin DNS loadbalancer by randomizing the order of A and AAAA records
- in the answer. See [Wikipedia](https://en.wikipedia.org/wiki/Round-robin_DNS) about the pros and
+ in the answer.
- cons on this setup.
  
-It will take care to sort any CNAMEs before any address records, because some stub resolver
+ See [Wikipedia](https://en.wikipedia.org/wiki/Round-robin_DNS) about the pros and cons on this
-implementations (like glibc) are particular about that.
+ setup. It will take care to sort any CNAMEs before any address records, because some stub resolver
+ implementations (like glibc) are particular about that.
 
 ## Syntax
 

middleware/metrics/README.md

@@ -1,8 +1,8 @@
 # prometheus
 
-This module enables prometheus metrics for CoreDNS. The default location for the metrics is
+This module enables prometheus metrics for CoreDNS.
-`localhost:9153`. The metrics path is fixed to `/metrics`.
 
+The default location for the metrics is `localhost:9153`. The metrics path is fixed to `/metrics`.
 The following metrics are exported:
 
 * coredns_dns_request_count_total{zone, proto, family}

middleware/pprof/README.md

@@ -1,8 +1,9 @@
 # pprof
 
-*pprof* publishes runtime profiling data at endpoints under /debug/pprof. You can visit
+*pprof* publishes runtime profiling data at endpoints under /debug/pprof.
- `/debug/pprof`
+
-on your site for an index of the available endpoints. By default it will listen on localhost:6053.
+You can visit `/debug/pprof` on your site for an index of the available endpoints. By default it
+will listen on localhost:6053.
 
 > This is a debugging tool. Certain requests (such as collecting execution traces) can be slow. If
 > you use pprof on a live site, consider restricting access or enabling it only temporarily.

middleware/proxy/README.md

@@ -1,9 +1,10 @@
 # proxy
 
-*proxy* facilitates both a basic reverse proxy and a robust load balancer. The proxy has support for
+*proxy* facilitates both a basic reverse proxy and a robust load balancer.
- multiple backends. The load balancing features include multiple policies, health checks, and
+
- failovers. If all hosts fail their health check the proxy middleware will fail back to randomly
+The proxy has support for multiple backends. The load balancing features include multiple policies,
- selecting a target and sending packets to it.
+health checks, and failovers. If all hosts fail their health check the proxy middleware will fail
+back to randomly selecting a target and sending packets to it.
 
 ## Syntax
 

middleware/rewrite/README.md

@@ -1,8 +1,9 @@
 # rewrite
 
-*rewrite* performs internal message rewriting. Rewrites are invisible to the client.
+*rewrite* performs internal message rewriting.
-There are simple rewrites (fast) and complex rewrites (slower), but they're powerful enough to
+
-accommodate most dynamic back-end applications.
+Rewrites are invisible to the client. There are simple rewrites (fast) and complex rewrites
+(slower), but they're powerful enough to accommodate most dynamic back-end applications.
 
 ## Syntax
 

middleware/root/README.md

@@ -1,8 +1,9 @@
 # root
 
 *root* simply specifies the root of where CoreDNS finds (e.g.) zone files.
-The default root is the current working directory of CoreDNS.
+
-A relative root path is relative to the current working directory.
+The default root is the current working directory of CoreDNS. A relative root path is relative to
+the current working directory.
 
 ## Syntax