[master] b36a9a37a Improve transit_buffer documentation

[Nils Goroll]

commit b36a9a37aaafef2c421000ecbe5cf5aaa5e9a239
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Tue Mar 14 13:16:30 2023 +0100

    Improve transit_buffer documentation
    
    - cross-reference parameter and vcl variable
    
    - clarify that a zero value means no limit (I found 'no buffering' confusing when
      in fact the full object is buffered, potentially)
    
    - improve wording, hopefully

diff --git a/doc/sphinx/reference/vcl_var.rst b/doc/sphinx/reference/vcl_var.rst
index 41bbe98db..49ec33f66 100644
--- a/doc/sphinx/reference/vcl_var.rst
+++ b/doc/sphinx/reference/vcl_var.rst
@@ -1067,8 +1067,12 @@ beresp.transit_buffer
 
 	Writable from: vcl_backend_response
 
+	Default: ``transit_buffer`` parameter, see :ref:`varnishd(1)`.
+
 	The maximum number of bytes the client can be ahead of the
-	backend during a streaming pass if ``beresp`` is uncacheable.
+	backend during a streaming pass if ``beresp`` is
+	uncacheable. See also ``transit_buffer`` parameter
+	documentation in :ref:`varnishd(1)`.
 
 
 beresp.ttl
diff --git a/include/tbl/params.h b/include/tbl/params.h
index 5ed5d7f86..cf46b1658 100644
--- a/include/tbl/params.h
+++ b/include/tbl/params.h
@@ -960,13 +960,21 @@ PARAM_SIMPLE(
 	/* def */	"0k",
 	/* units */	"bytes",
 	/* descr */
-	"The amount of buffer allowed through Varnish for uncacheable "
-	"backend streaming fetches. Zero means that no buffering is "
-	"done and the object is fetched as fast as possible.\n\n"
-	"When a client is slow, this can prevent large uncacheable objects "
-	"from being stored indefinitely when the intent is to simply stream "
-	"them to the client. As a result, a slow client transaction holds "
-	"onto a backend connection until the end of the delivery."
+
+	"The number of bytes which Varnish buffers for uncacheable "
+	"backend streaming fetches - in other words, how many bytes "
+	"Varnish reads from the backend ahead of what has been sent to "
+	"the client.\n"
+	"A zero value means no limit, the object is fetched as fast as "
+	"possible.\n\n"
+	"When dealing with slow clients, setting this parameter to "
+	"non-zero can prevent large uncacheable objects from being "
+	"stored in full when the intent is to simply stream them to the "
+	"client. As a result, a slow client transaction holds onto a "
+	"backend connection until the end of the delivery.\n\n"
+	"This parameter is the default to the VCL variable "
+	"``beresp.transit_buffer``, which can be used to control the "
+	"transit buffer per backend request."
 )
 
 PARAM_SIMPLE(