Add missing returns, and do a bit of cleanup

doc/sphinx/users-guide/vcl-built-in-subs.rst

@@ -22,8 +22,8 @@ yourself doing frequently.
 The `vcl_recv` subroutine may terminate with calling ``return()`` on one
 of the following keywords:
 
-  synth 
-    Return a synthetic object with the specified error code to the
+  synth(status code, reason)
+    Return a synthetic object with the specified status code to the
     client and abandon the request.
 
   pass
@@ -52,8 +52,8 @@ shuffling bytes back and forth.
 The `vcl_pipe` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
-  synth(error code, reason)
-    Return the specified error code to the client and abandon the request.
+  synth(status code, reason)
+    Return the specified status code to the client and abandon the request.
 
   pipe
     Proceed with pipe mode.
@@ -69,8 +69,8 @@ submitted over the same client connection are handled normally.
 The `vcl_pass` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
-  synth(error code, reason)
-    Return the specified error code to the client and abandon the request.
+  synth(status code, reason)
+    Return the specified status code to the client and abandon the request.
 
   pass
     Proceed with pass mode.
@@ -86,7 +86,7 @@ vcl_hit
 
 Called when a cache lookup is successful. 
 
-.. XXX: missing the "The `vcl_hit` subroutine may terminate with calling ``return()`` with one of the following keywords:" thing. benc
+The `vcl_hit` subroutine may terminate with calling ``return()`` with one of the following keywords:
 
 
   restart
@@ -97,8 +97,8 @@ Called when a cache lookup is successful.
   deliver
     Deliver the object. Control passes to `vcl_deliver`.
 
-  synth(error code, reason)
-    Return the specified error code to the client and abandon the request.
+  synth(status code, reason)
+    Return the specified status code to the client and abandon the request.
 
 
 vcl_miss
@@ -111,8 +111,8 @@ retrieve the document from the backend, and which backend to use.
 The `vcl_miss` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
-  synth(error code, reason)
-    Return the specified error code to the client and abandon the request.
+  synth(status code, reason)
+    Return the specified status code to the client and abandon the request.
 
   pass
     Switch to pass mode. Control will eventually pass to `vcl_pass`.
@@ -121,38 +121,51 @@ of the following keywords:
     Retrieve the requested object from the backend. Control will
     eventually pass to `vcl_backend_fetch`.
 
+  restart
+    Restart the transaction. Increases the restart counter. If the number
+    of restarts is higher than *max_restarts* Varnish emits a guru meditation
+    error.
+
+
 vcl_hash
 ~~~~~~~~
 
 Called after `vcl_recv` to create a hash value for the request. This is
 used as a key to look up the object in Varnish.
 
+The `vcl_hash` subroutine may terminate with calling ``return()`` with one
+of the following keywords:
+
   lookup
     Look up the object in cache. Control passes to vcl_miss, vcl_hit
     or vcl_purge.
 
 
-
-
 vcl_purge
 ~~~~~~~~~
 
 Called after the purge has been executed and all its variants have been evited.
 
+The `vcl_purge` subroutine may terminate with calling ``return()`` with one
+of the following keywords:
+
   synth
     Produce a response.
 
+  restart
+    Restart the transaction. Increases the restart counter. If the number
+    of restarts is higher than *max_restarts* Varnish emits a guru meditation
+    error.
+
 
 vcl_deliver
 ~~~~~~~~~~~
 
 Called before a cached object is delivered to the client.
 
-The ``vcl_deliver`` subroutine may terminate calling ``return()`` with one
+The `vcl_deliver` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
-.. XXX: Should perhaps be return as above? benc
-
   deliver
     Deliver the object to the client.
 
@@ -168,7 +181,8 @@ vcl_backend_fetch
 Called before sending the backend request. In this subroutine you
 typically alter the request before it gets to the backend.
 
-.. XXX: Missing terminate..keywords sentence? benc
+The `vcl_backend_fetch` subroutine may terminate with calling
+``return()`` with one of the following keywords:
 
   fetch
     Fetch the object from the backend.
@@ -180,71 +194,40 @@ typically alter the request before it gets to the backend.
 vcl_backend_response
 ~~~~~~~~~~~~~~~~~~~~
 
-Called after a response has been successfully retrieved from the
-backend. The response is available as `beresp`. 
-
-.. XXX: beresp comes out of the blue here. maybe a short description? benc
-
-Note that Varnish might
-not be talking to an actual client, so operations that require a
-client to be present are not allowed. Specifically there is no `req
-object` and restarts are not allowed.
+Called after the response headers has been successfully retrieved from
+the backend.
 
-.. XXX: I do not follow sentence above. benc
-
-The `vcl_backend_response` subroutine may terminate with calling ``return()`` with one
-of the following keywords:
+The `vcl_backend_response` subroutine may terminate with calling
+``return()`` with one of the following keywords:
 
   deliver
     Possibly insert the object into the cache, then deliver it to the
     Control will eventually pass to `vcl_deliver`. Caching is dependant
     on 'beresp.cacheable'.
 
-.. XXX:A parameter? that is set how? benc
-    
-
-  error(error code, reason)
-    Return the specified error code to the client and abandon the request.
+  abandon
+    Abandon the backend request and generates an error.
 
   retry
-    Retry the backend transaction. Increases the `retries` counter. If the number
-    of retries is higher than *max_retries* Varnish emits a guru meditation
-    error.
+    Retry the backend transaction. Increases the `retries` counter.
+    If the number of retries is higher than *max_retries* Varnish
+    emits a guru meditation error.
 
 vcl_backend_error
 ~~~~~~~~~~~~~~~~~
 
 This subroutine is called if we fail the backend fetch. 
 
-.. XXX:Missing the terminate return structure? benc
+The `vcl_backend_error` subroutine may terminate with calling ``return()``
+with one of the following keywords:
 
   deliver
     Deliver the error.
 
   retry
-    Retry the backend transaction. Increases the `retries` counter. If the number
-    of retries is higher than *max_retries* Varnish emits a guru meditation
-    error.
-
-
-vcl_backend_error
-~~~~~~~~~~~~~~~~~
-
-.. XXX: Same name as section above? benc
-
-Called when we hit an error, either explicitly or implicitly due to
-backend or internal errors.
-
-The `vcl_backend_error` subroutine may terminate by calling ``return()`` with one of
-the following keywords:
-
-  deliver
-    Deliver the error object to the client.
-
-  retry
-    Retry the backend transaction. Increases the retries counter. If the number
-    of retries is higher than *max_retries* Varnish emits a guru meditation
-    error.
+    Retry the backend transaction. Increases the `retries` counter. If
+    the number of retries is higher than *max_retries* Varnish emits a
+    guru meditation error.
 
 
 vcl_init
@@ -253,9 +236,8 @@ vcl_init
 Called when VCL is loaded, before any requests pass through it.
 Typically used to initialize VMODs.
 
-.. XXX: Missing the terminate return structure? benc
-
-  ``return()`` values:
+The `vcl_init` subroutine may terminate with calling ``return()``
+with one of the following keywords:
 
   ok
     Normal return, VCL continues loading.
@@ -267,13 +249,8 @@ vcl_fini
 Called when VCL is discarded only after all requests have exited the VCL.
 Typically used to clean up VMODs.
 
-
-.. XXX: Missing the terminate return structure? benc
-
-  ``return()`` values:
+The `vcl_fini` subroutine may terminate with calling ``return()``
+with one of the following keywords:
 
   ok
     Normal return, VCL will be discarded.
-
-
-.. XXX: Maybe end here with the detailed flowchart from the book together with a reference to the book? benc