[master] 7872e8179 Document correctly vcl_hit built-in VCL

[Nils Goroll]

commit 7872e81793317246d52b79760b64b5001c537ad6
Author: Pål Hermunn Johansen <hermunn at varnish-software.com>
Date:   Fri Sep 4 21:22:27 2020 +0200

    Document correctly vcl_hit built-in VCL
    
    It has been a while since the built-in vcl_hit changed, and this
    updates the user guide.
    
    Since 6.0.1 we have had the corresponding change in TTL, grace, keep
    change, and this is also mentioned.

diff --git a/doc/sphinx/users-guide/vcl-grace.rst b/doc/sphinx/users-guide/vcl-grace.rst
index fcaa301bb..afaac2ce4 100644
--- a/doc/sphinx/users-guide/vcl-grace.rst
+++ b/doc/sphinx/users-guide/vcl-grace.rst
@@ -90,31 +90,19 @@ new object is in it will replace the one we've already got.
 If you do not define your own ``sub vcl_hit``, then the default one is
 used. It looks like this::
 
-  sub vcl_hit {
-       if (obj.ttl >= 0s) {
-            // A pure unadulterated hit, deliver it
-            return (deliver);
-       }
-       if (obj.ttl + obj.grace > 0s) {
-            // Object is in grace, deliver it
-            // Automatically triggers a background fetch
-            return (deliver);
-       }
-       // fetch & deliver once we get the result
-       return (miss);
-  }
-
-The effect of the built-in VCL is in fact equivalent to the following::
-
   sub vcl_hit {
        return (deliver);
   }
 
-This is because ``obj.ttl + obj.grace > 0s`` always will evaluate to
-true. However, the the VCL is as it is to show users how to
-differentiate between a pure hit and a `grace` hit. With the next
-major version of Varnish, the default VCL is planned to change to the
-latter, shorter version.
+Note that the condition ``obj.ttl + obj.grace > 0s`` will (in ``sub
+vcl_hit``) always evaluate to true. In earlier versions (6.0.0 and
+earlier), this was not the case, and a test in the builtin VCL was
+necessary to make sure that "keep objects" (objects in the cache where
+both TTL and grace had run out) would not be delivered to the clients.
+
+In the current version, when there are only "keep objects" available,
+``sub vcl_miss`` will be called, and a fetch for a new object will be
+initiated.
 
 Misbehaving servers
 ~~~~~~~~~~~~~~~~~~~