Add docs (#427)

Provide TTL examples for cache middleware. Fixes: #364

Add interaction docs to make non invalidation for cache middleware
clear. Cache might serve stale records. Fixes: #403

1 files changed, 6 insertions, 4 deletions

diff --git a/middleware/cache/README.md b/middleware/cache/README.md
index e952f058b..145ce2fdf 100644
--- a/middleware/cache/README.md
+++ b/middleware/cache/README.md
@@ -1,6 +1,6 @@
 # cache
 
-*cache* enables a frontend cache.
+*cache* enables a frontend cache. It will cache all records except zone transfers and metadata records.
 
 ## Syntax
 
@@ -8,13 +8,15 @@
 cache [TTL] [ZONES...]
 ~~~
 
-* **TTL** max TTL in seconds. If not specified, the maximum TTL will be used which is 1 hour for
-    noerror responses and half an hour for denial of existence ones.
+* **TTL** max TTL in seconds. If not specified, the maximum TTL will be used which is 3600 for
+    noerror responses and 1800 for denial of existence ones.
+    A set TTL of 300 *cache 300* would cache the record up to 300 seconds.
+    Smaller record provided TTLs will take precedence.
 * **ZONES** zones it should cache for. If empty, the zones from the configuration block are used.
 
 Each element in the cache is cached according to its TTL (with **TTL** as the max).
 For the negative cache, the SOA's MinTTL value is used. A cache can contain up to 10,000 items by
-default. A TTL of zero is not allowed.
+default. A TTL of zero is not allowed. No cache invalidation triggered by other middlewares is available. Therefore even reloaded items might still be cached for the duration of the TTL.
 
 If you want more control: