[6.0] 625d855d0 add HTC errors to the documentation

[Dridi Boukelmoune]

commit 625d855d02cbfabdd809d5178d8aa0907782a392
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Mon Sep 10 20:10:25 2018 +0200

    add HTC errors to the documentation
    
    Conflicts:
            doc/sphinx/whats-new/upgrading-6.1.rst

diff --git a/include/tbl/htc.h b/include/tbl/htc.h
index a46b75e28..a93c0e520 100644
--- a/include/tbl/htc.h
+++ b/include/tbl/htc.h
@@ -35,11 +35,11 @@
 HTC_STATUS(JUNK,	-5,	"junk",		"Received unexpected data")
 HTC_STATUS(CLOSE,	-4,	"close",	"Connection closed") // unused?
 HTC_STATUS(TIMEOUT,	-3,	"timeout",	"Timed out")
-HTC_STATUS(OVERFLOW,	-2,	"overflow",	"Buffer too small")
-HTC_STATUS(EOF,	-1,	"eof",		"EOF received")
+HTC_STATUS(OVERFLOW,	-2,	"overflow",	"Buffer/workspace too small")
+HTC_STATUS(EOF,	-1,	"eof",		"Unexpected end of input")
 HTC_STATUS(EMPTY,	 0,	"empty",	"Empty response")
 HTC_STATUS(MORE,	 1,	"more",	"More data required")
-HTC_STATUS(COMPLETE,	 2,	"complete",	"Data complete")
-HTC_STATUS(IDLE,	 3,	"idle",	"Return to waiter")
+HTC_STATUS(COMPLETE,	 2,	"complete",	"Data complete (no error)")
+HTC_STATUS(IDLE,	 3,	"idle",	"Connection was closed while idle")
 #undef HTC_STATUS
 /*lint -restore */
diff --git a/include/tbl/vsl_tags.h b/include/tbl/vsl_tags.h
index ac93f15b7..6e7b81031 100644
--- a/include/tbl/vsl_tags.h
+++ b/include/tbl/vsl_tags.h
@@ -165,9 +165,32 @@ SLTM(Length, 0, "Size of object body",
 	"Logs the size of a fetch object body.\n\n"
 )
 
+/* XXX generate HTC info from tbl include */
+#if 0
+#include <stdio.h>
+int main(void) {
+#define HTC_STATUS(e, n, s, l) \
+	printf("\t\"\\t* %s (%d): %s\\n\"\n", s, n, l);
+#include "include/tbl/htc.h"
+	return (0);
+}
+#endif
+
 SLTM(FetchError, 0, "Error while fetching object",
 	"Logs the error message of a failed fetch operation.\n\n"
-)
+	"Error messages should be self-explanatory, yet the http connection"
+	"(HTC) class of errors is reported with these symbols:\n\n"
+	"\t* junk (-5): Received unexpected data\n"
+	"\t* close (-4): Connection closed\n"
+	"\t* timeout (-3): Timed out\n"
+	"\t* overflow (-2): Buffer/workspace too small\n"
+	"\t* eof (-1): Unexpected end of input\n"
+	"\t* empty (0): Empty response\n"
+	"\t* more (1): More data required\n"
+	"\t* complete (2): Data complete (no error)\n"
+	"\t* idle (3): Connection was closed while idle\n"
+	"\nNotice that some HTC errors are never emitted."
+	)
 
 #define SLTH(tag, ind, req, resp, sdesc, ldesc) \
 	SLTM(Req##tag, (req ? 0 : SLT_F_UNUSED), "Client request " sdesc, ldesc)