add HTC errors to the documentation

doc/sphinx/whats-new/upgrading-6.1.rst

@@ -179,6 +179,9 @@ Other changes
     give better human-readable diagnostics for certain classes of
     backend fetch failures.
 
+    In particular, http connection (HTC) errors are now reported
+    symbolically in addition to the previous numerical value.
+
   * ``Debug`` log entries may also give more diagnostic information
     about session accept failures (failure to accept a client
     connection). These must be viewed in raw grouping, since accept

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 */

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)