[master] b1e9f69ad vcl_step: Document that return(fail) can take a string argument

[Walid Boudebouda]

commit b1e9f69ad5dfd723cade06b33db0714a137a2d82
Author: Walid Boudebouda <walid.boudebouda at gmail.com>
Date:   Fri Aug 29 18:41:06 2025 +0200

    vcl_step: Document that return(fail) can take a string argument

diff --git a/doc/sphinx/reference/vcl-step.rst b/doc/sphinx/reference/vcl-step.rst
index fd33764c0..683f48420 100644
--- a/doc/sphinx/reference/vcl-step.rst
+++ b/doc/sphinx/reference/vcl-step.rst
@@ -61,13 +61,17 @@ Common actions for the client and backend side
 
 .. _fail:
 
-``fail``
-~~~~~~~~
+``fail(err)``
+~~~~~~~~~~~~~
 
     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.
+    connection close. The optional string argument `err` is logged to
+    VSL under a `VCL_Error` tag.
+
+    Returning `fail` from `vcl_synth` sends a minimal response with a 500
+    status.
 
     Intended for fatal errors, for which only minimal error handling is
     possible.
diff --git a/doc/sphinx/reference/vcl_step.rst b/doc/sphinx/reference/vcl_step.rst
index 794f4fb76..3b2f48a6f 100644
--- a/doc/sphinx/reference/vcl_step.rst
+++ b/doc/sphinx/reference/vcl_step.rst
@@ -24,7 +24,7 @@ The `vcl_recv` subroutine may terminate with calling ``return()`` on one
 of the following keywords:
 
   |
-  | ``fail``
+  | ``fail(err)``
   |  see :ref:`fail` section above
   |
   | ``synth(status code, reason)``
@@ -75,7 +75,7 @@ The `vcl_pipe` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
   |
-  | ``fail``
+  | ``fail(err)``
   |  see :ref:`fail` section above
   |
   | ``synth(status code, reason)``
@@ -98,7 +98,7 @@ The `vcl_pass` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
   |
-  | ``fail``
+  | ``fail(err)``
   |  see :ref:`fail` section above
   |
   | ``synth(status code, reason)``
@@ -122,7 +122,7 @@ The `vcl_hash` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
   |
-  | ``fail``
+  | ``fail(err)``
   |  see  :ref:`fail` section above
   |
   | ``lookup``
@@ -154,7 +154,7 @@ The `vcl_purge` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
   |
-  | ``fail``
+  | ``fail(err)``
   |  see :ref:`fail` section above
   |
   | ``synth(status code, reason)``
@@ -179,7 +179,7 @@ The `vcl_miss` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
   |
-  | ``fail``
+  | ``fail(err)``
   |  see :ref:`fail` section above
   |
   | ``synth(status code, reason)``
@@ -207,7 +207,7 @@ stale: It can have a zero or negative `ttl` with only `grace` or
 The `vcl_hit` subroutine may terminate with calling ``return()``
 with one of the following keywords:
 
-  | ``fail``
+  | ``fail(err)``
   |  see :ref:`fail` section above
   |
   | ``synth(status code, reason)``
@@ -234,7 +234,7 @@ The `vcl_deliver` subroutine may terminate with calling ``return()`` with one
 of the following keywords:
 
   |
-  | ``fail``
+  | ``fail(err)``
   |  see :ref:`fail` section above
   |
   | ``synth(status code, reason)``
@@ -262,7 +262,7 @@ The subroutine may terminate with calling ``return()`` with one of the
 following keywords:
 
   |
-  | ``fail``
+  | ``fail(err)``
   |  see :ref:`fail` section above
   |
   | ``restart``
@@ -287,7 +287,7 @@ The `vcl_backend_fetch` subroutine may terminate with calling
 ``return()`` with one of the following keywords:
 
   |
-  | ``fail``
+  | ``fail(err)``
   |  see :ref:`fail` section above
   |
   | ``abandon``
@@ -388,7 +388,7 @@ The `vcl_backend_response` subroutine may terminate with calling
 ``return()`` with one of the following keywords:
 
   |
-  | ``fail``
+  | ``fail(err)``
   |  see :ref:`fail` section above
   |
   | ``abandon``
@@ -438,7 +438,7 @@ The `vcl_backend_error` subroutine may terminate with calling ``return()``
 with one of the following keywords:
 
   |
-  | ``fail``
+  | ``fail(err)``
   |  see :ref:`fail` section above
   |
   | ``abandon``
@@ -473,7 +473,7 @@ with one of the following keywords:
   | ``ok``
   |  Normal return, VCL continues loading.
   |
-  | ``fail``
+  | ``fail(err)``
   |  Abort loading of this VCL.
 
 .. _vcl_fini: