[master] 8f3f5b57c Centralize the VCL status code documentation

[Dridi Boukelmoune]

commit 8f3f5b57c811f750704e6e1e085706642be08e6c
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Tue May 12 09:03:38 2020 +0200

    Centralize the VCL status code documentation

diff --git a/doc/sphinx/reference/vcl_var.rst b/doc/sphinx/reference/vcl_var.rst
index 300ea0a22..30aef93cf 100644
--- a/doc/sphinx/reference/vcl_var.rst
+++ b/doc/sphinx/reference/vcl_var.rst
@@ -702,13 +702,7 @@ beresp.status
 
 	The HTTP status code returned by the server.
 
-	Status codes on the form XXYZZ can be set where
-	XXYZZ is less than 65536 and Y is [1...9].
-	Only YZZ will be sent back to clients.
-
-	XX can be therefore be used to pass information
-	around inside VCL, for instance ``return(synth(22404))``
-	from ``vcl_recv{}`` to ``vcl_synth{}``
+	More information in the `HTTP response status`_ section.
 
 beresp.reason
 
@@ -1028,6 +1022,8 @@ obj.status
 
 	The HTTP status code stored in the object.
 
+	More information in the `HTTP response status`_ section.
+
 
 obj.reason
 
@@ -1183,12 +1179,7 @@ resp.status
 
 	The HTTP status code that will be returned.
 
-	Assigning a HTTP standardized code to resp.status will also
-	set resp.reason to the corresponding status message.
-
-	Status codes on the form XXYZZ can be set where
-	XXYZZ is less than 65536 and Y is [1...9].
-	Only YZZ will be sent back to clients.
+	More information in the `HTTP response status`_ section.
 
 	resp.status 200 will get changed into 304 by core code after
 	a return(deliver) from vcl_deliver for conditional requests
@@ -1389,3 +1380,29 @@ storage.<name>.happy
 	Health status for the named stevedore. Not available in any of the
 	current stevedores.
 
+HTTP response status
+--------------------
+
+A status code normally has 3 digits XYZ where X must be between 1 and 5
+included. Since it is not uncommon to see HTTP clients or servers relying
+on non-standard or even invalid status codes Varnish tolerates any status
+between 100 and 999.
+
+With VCL code it is possible to use status codes in the form XXYZZ where the
+overall value is lower than 65536 and the Y digit is between 1 and 9 included.
+Only the YZZ part is sent to the client.
+
+The XXYZZ form of status codes can be set on ``resp.status`` and
+``beresp.status`` or passed via ``return(synth(...))`` and
+``return(error(...))`` transitions.
+
+XX can be therefore be used to pass information around inside VCL, for
+instance ``return(synth(22404))`` from ``vcl_recv{}`` to ``vcl_synth{}``.
+
+The ``obj.status`` variable will inherit the XXYZZ form, but in a ban
+expresion only the YZZ part will be available. The XXYZZ form is strictly
+limited to VCL execution.
+
+Assigning an HTTP standardized code to ``resp.status`` or ``beresp.status``
+will also set ``resp.reason`` or ``beresp.reason``  to the corresponding
+status message.