Improve return(<action>) documentation

We had two places where we documented common actions, and one of them
was outdated.

doc/sphinx/users-guide/vcl-actions.rst

 .. _user-guide-vcl_actions:
 
-actions
-~~~~~~~
+Actions
+=======
 
-The most common actions to return are these:
+Actions are used with the ``return(<action>)`` keyword, which returns
+control from subroutines back to varnish. The action determines how
+processing in varnish continues as shown in :ref:`reference-states`.
 
-.. XXX:Maybe a bit more explanation here what is an action and how it is returned? benc
+Common actions are documented here, while additional actions specific
+to only one or some subroutines are documented in
+:ref:`vcl-built-in-subs` as well as which action can be used from
+which built in subroutine.
 
-*pass*
-  When you return pass the request and subsequent response will be passed to
-  and from the backend server. It won't be cached. `pass` can be returned from
-  `vcl_recv`.
+common actions for the client and backend side
+----------------------------------------------
 
-*hash*
-  When you return hash from `vcl_recv` you tell Varnish to deliver content
-  from cache even if the request otherwise indicates that the request
-  should be passed.
+.. _fail:
 
-*pipe*
+``fail``
+~~~~~~~~
 
-.. XXX:What is pipe? benc
+    Transition to :ref:`vcl_synth` on the client side as for
+    ``return(synth(503, "VCL Failed"))``, but with any request state
+    changes undone as if ``std.rollback()`` was called and forcing a
+    connection close.
 
-  Pipe can be returned from `vcl_recv` as well. Pipe short circuits the
-  client and the backend connections and Varnish will just sit there
-  and shuffle bytes back and forth. Varnish will not look at the data being
-  send back and forth - so your logs will be incomplete.
+    Intended for fatal errors, for which only minimal error handling is
+    possible.
 
-*deliver*
-  Deliver the object to the client. Usually returned from `vcl_backend_response`.
+common actions for the client side
+----------------------------------
 
-*restart*
-  Restart processing of the request. You can restart the processing of
-  the whole transaction. Changes to the `req` object are retained, except
-  for `req.backend_hint`, which gets reset to the default backend.
+.. _synth:
 
-*retry*
-  Retry the request against the backend. This can be returned from
-  `vcl_backend_response` or `vcl_backend_error` if you don't like the response
-  that the backend delivered.
+``synth(status code, reason)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Transition to :ref:`vcl_synth` with ``resp.status`` and
+    ``resp.reason`` being preset to the arguments of ``synth()``.
+
+.. _pass:
+
+``pass``
+~~~~~~~~
+
+    Switch to pass mode, making the current request not use the cache
+    and not putting its response into it. Control will eventually pass to
+    :ref:`vcl_pass`.
+
+.. _pipe:
+
+``pipe``
+~~~~~~~~
+
+    Switch to pipe mode. Control will eventually pass to
+    :ref:`vcl_pipe`.
+
+.. _restart:
+
+``restart``
+~~~~~~~~~~~
+
+    Restart the transaction. Increases the ``req.restarts`` counter.
+
+    If the number of restarts is higher than the *max_restarts*
+    parameter, control is passed to :ref:`vcl_synth` as for
+    ``return(synth(503, "Too many restarts"))``
+
+    For a restart, all modifications to ``req`` attributes are
+    preserved except for ``req.restarts`` and ``req.xid``, which need
+    to change by design.
+
+common actions for the backend side
+-----------------------------------
+
+.. _abandon:
+
+``abandon``
+~~~~~~~~~~~
+
+    Abandon the backend request. Unless the backend request was a
+    background fetch, control is passed to :ref:`vcl_synth` on the
+    client side with ``resp.status`` preset to 503.

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

@@ -9,64 +9,21 @@ and backend requests as well as upon ``vcl.load`` and ``vcl.discard``.
 See :ref:`reference-states` for a detailed graphical overview of the
 states and how they relate to core code functions and VCL subroutines.
 
-Subroutines always terminate with a ``return()`` on a keyword, which
-determines how processing continues in the request processing state
-machine.
+Built-in subroutines always terminate with a ``return(<action>)``,
+where ``<action>`` determines how processing continues in the request
+processing state machine.
 
-The behaviour for ``return()`` keywords is identical or at least
-similar across subroutines, so differences are only documented where
-relevant.
+The behaviour of actions is identical or at least similar across
+subroutines, so differences are only documented where relevant.
 
-common return keywords for the client and backend side
-------------------------------------------------------
+Common actions are documented in
+:ref:`user-guide-vcl_actions`. Actions specific to only one or some
+subroutines are documented herein.
 
-.. _fail:
-
-  ``fail``
-    Transition to :ref:`vcl_synth` on the client side as for
-    ``return(synth(503, "VCL Failed"))``, but with any request state
-    changes undone as if ``std.rollback()`` was called and forcing a
-    connection close.
-
-    Intended for fatal errors, for which only minimal error handling is
-    possible.
 
 client side
 -----------
 
-common return keywords for the client side
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. _synth:
-
-  ``synth(status code, reason)``
-    Transition to :ref:`vcl_synth` with ``resp.status`` and
-    ``resp.reason`` being preset to the arguments of ``synth()``.
-
-.. _pass:
-
-  ``pass``
-    Switch to pass mode. Control will eventually pass to
-    :ref:`vcl_pass`.
-
-.. _pipe:
-
-  ``pipe``
-    Switch to pipe mode. Control will eventually pass to
-    :ref:`vcl_pipe`.
-
-.. _restart:
-
-  ``restart``
-    Restart the transaction. Increases the ``req.restarts`` counter.
-
-    If the number of restarts is higher than the *max_restarts*
-    parameter, control is passed to :ref:`vcl_synth` as for
-    ``return(synth(503, "Too many restarts"))``
-
-    For a restart, all modifications to ``req`` attributes are
-    preserved except for ``req.restarts`` and ``req.xid``, which need
-    to change by design.
-
 .. _vcl_recv:
 
 vcl_recv
@@ -84,19 +41,19 @@ The `vcl_recv` subroutine may terminate with calling ``return()`` on one
 of the following keywords:
 
   ``fail``
-    see `fail`_
+    see :ref:`fail`
 
   ``synth(status code, reason)``
-    see `synth`_
+    see :ref:`synth`
 
   ``restart``
-    see `restart`_
+    see :ref:`restart`
 
   ``pass``
-    see `pass`_
+    see :ref:`pass`
 
   ``pipe``
-    see `pipe`_
+    see :ref:`pipe`
 
   ``hash``
     Continue processing the object as a potential candidate for
@@ -134,10 +91,10 @@ The `vcl_pipe` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
   ``fail``
-    see   `fail`_
+    see   :ref:`fail`
 
   ``synth(status code, reason)``
-    see  `synth`_
+    see  :ref:`synth`
 
   ``pipe``
     Proceed with pipe mode.
@@ -156,13 +113,13 @@ The `vcl_pass` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
   ``fail``
-    see  `fail`_
+    see  :ref:`fail`
 
   ``synth(status code, reason)``
-    see  `synth`_
+    see  :ref:`synth`
 
   ``restart``
-    see  `restart`_
+    see  :ref:`restart`
 
   ``fetch``
     Proceed with pass mode - initiate a backend request.
@@ -179,7 +136,7 @@ The `vcl_hash` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
   ``fail``
-    see  `fail`_
+    see  :ref:`fail`
 
   ``lookup``
     Look up the object in cache.
@@ -210,13 +167,13 @@ The `vcl_purge` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
   ``fail``
-    see  `fail`_
+    see  :ref:`fail`
 
   ``synth(status code, reason)``
-    see  `synth`_
+    see  :ref:`synth`
 
   ``restart``
-    see  `restart`_
+    see  :ref:`restart`
 
 .. _vcl_miss:
 
@@ -234,16 +191,16 @@ The `vcl_miss` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
   ``fail``
-    see  `fail`_
+    see  :ref:`fail`
 
   ``synth(status code, reason)``
-    see  `synth`_
+    see  :ref:`synth`
 
   ``restart``
-    see  `restart`_
+    see  :ref:`restart`
 
   ``pass``
-    see  `pass`_
+    see  :ref:`pass`
 
   ``fetch``
     Retrieve the requested object from the backend. Control will
@@ -262,16 +219,16 @@ The `vcl_hit` subroutine may terminate with calling ``return()``
 with one of the following keywords:
 
   ``fail``
-    see  `fail`_
+    see  :ref:`fail`
 
   ``synth(status code, reason)``
-    see  `synth`_
+    see  :ref:`synth`
 
   ``restart``
-    see  `restart`_
+    see  :ref:`restart`
 
   ``pass``
-    see  `pass`_
+    see  :ref:`pass`
 
   ``deliver``
     Deliver the object. If it is stale, a background fetch to refresh
@@ -288,13 +245,13 @@ The `vcl_deliver` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
   ``fail``
-    see  `fail`_
+    see  :ref:`fail`
 
   ``synth(status code, reason)``
-    see  `synth`_
+    see  :ref:`synth`
 
   ``restart``
-    see  `restart`_
+    see  :ref:`restart`
 
   ``deliver``
     Deliver the object to the client.
@@ -315,10 +272,10 @@ The subroutine may terminate with calling ``return()`` with one of the
 following keywords:
 
   ``fail``
-    see  `fail`_
+    see  :ref:`fail`
 
   ``restart``
-    see  `restart`_
+    see  :ref:`restart`
 
   ``deliver``
     Directly deliver the object defined by `vcl_synth` to the client
@@ -327,17 +284,6 @@ following keywords:
 Backend Side
 ------------
 
-
-common return keywords for the backend side
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. _abandon:
-
-  ``abandon``
-    Abandon the backend request. Unless the backend request was a
-    background fetch, control is passed to :ref:`vcl_synth` on the
-    client side with ``resp.status`` preset to 503.
-
 .. _vcl_backend_fetch:
 
 vcl_backend_fetch
@@ -350,10 +296,10 @@ The `vcl_backend_fetch` subroutine may terminate with calling
 ``return()`` with one of the following keywords:
 
   ``fail``
-    see  `fail`_
+    see  :ref:`fail`
 
   ``abandon``
-    see  `abandon`_
+    see  :ref:`abandon`
 
   ``fetch``
     Fetch the object from the backend.
@@ -403,10 +349,10 @@ The `vcl_backend_response` subroutine may terminate with calling
 ``return()`` with one of the following keywords:
 
   ``fail``
-    see  `fail`_
+    see  :ref:`fail`
 
   ``abandon``
-    see  `abandon`_
+    see  :ref:`abandon`
 
   ``deliver``
     For a 304 response, create an updated cache object.
@@ -507,7 +453,7 @@ vcl_backend_error
 This subroutine is called if we fail the backend fetch or if
 *max_retries* has been exceeded.
 
-Returning with `abandon`_ does not leave a cache object.
+Returning with :ref:`abandon` does not leave a cache object.
 
 If returning with ``deliver`` and a ``beresp.ttl > 0s``, a synthetic
 cache object is generated in VCL, whose body may be constructed using
@@ -527,10 +473,10 @@ The `vcl_backend_error` subroutine may terminate with calling ``return()``
 with one of the following keywords:
 
   ``fail``
-    see  `fail`_
+    see  :ref:`fail`
 
   ``abandon``
-    see  `abandon`_
+    see  :ref:`abandon`
 
   ``deliver``
     Deliver and possibly cache the object defined in