[master] 75c7f15a6 doc: Bring back changes to vcl-hashing.rst

[Dridi Boukelmoune]

commit 75c7f15a6c061f67e38ba147a577181f1675ceb1
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date:   Tue Mar 2 16:23:05 2021 +0100

    doc: Bring back changes to vcl-hashing.rst
    
    On their own, those changes improve the documentation and don't mention
    the reverted "hash_data() in vcl_recv" feature.
    
    Refs e98e8e6497b9

diff --git a/doc/sphinx/users-guide/vcl-hashing.rst b/doc/sphinx/users-guide/vcl-hashing.rst
index c605f5589..1f50a5e63 100644
--- a/doc/sphinx/users-guide/vcl-hashing.rst
+++ b/doc/sphinx/users-guide/vcl-hashing.rst
@@ -6,12 +6,10 @@
 Hashing
 -------
 
-Internally, when Varnish stores content in the cache it stores the object
-together with a hash key to find the object again. In the default setup
-this key is calculated based on the content of the *Host* header or the
-IP address of the server and the URL.
-
-Behold the `default vcl`::
+Internally, when Varnish stores content in the cache indexed by a hash
+key used to find the object again. In the default setup
+this key is calculated based on `URL`, the `Host:` header, or
+if there is none, the IP address of the server::
 
     sub vcl_hash {
         hash_data(req.url);
@@ -23,7 +21,7 @@ Behold the `default vcl`::
         return (lookup);
     }
 
-As you can see it first checks in `req.url` then `req.http.host` if
+As you can see it first hashes `req.url` and then `req.http.host` if
 it exists. It is worth pointing out that Varnish doesn't lowercase the
 hostname or the URL before hashing it so in theory having "Varnish.org/"
 and "varnish.org/" would result in different cache entries. Browsers
@@ -47,7 +45,16 @@ And then add a `vcl_hash`::
         hash_data(req.http.X-Country-Code);
     }
 
-As the default VCL will take care of adding the host and URL to the hash
-we don't have to do anything else. Be careful calling ``return (lookup)``
-as this will abort the execution of the default VCL and Varnish can end
-up returning data based on more or less random inputs.
+Because there is no `return(lookup)`, the builtin VCL will take care
+of adding the URL, `Host:` or server IP# to the hash as usual.
+
+If `vcl_hash` did return, ie::
+
+    sub vcl_hash {
+        hash_data(req.http.X-Country-Code);
+        return(lookup);
+    }
+
+then *only* the country-code would matter, and Varnish would return
+seemingly random objects, ignoring the URL, (but they would always
+have the correct `X-Country-Code`).