diff --git a/include/libwebsockets/lws-callbacks.h b/include/libwebsockets/lws-callbacks.h
index 77372f274..a31ab74cd 100644
--- a/include/libwebsockets/lws-callbacks.h
+++ b/include/libwebsockets/lws-callbacks.h
@@ -346,19 +346,23 @@ enum lws_callback_reasons {
 	 * one callback. */
 
 	LWS_CALLBACK_RECEIVE_CLIENT_HTTP			= 46,
-	/**< This simply indicates data was received on the HTTP client
-	 * connection.  It does NOT drain or provide the data.
-	 * This exists to neatly allow a proxying type situation,
-	 * where this incoming data will go out on another connection.
-	 * If the outgoing connection stalls, we should stall processing
-	 * the incoming data.  So a handler for this in that case should
-	 * simply set a flag to indicate there is incoming data ready
-	 * and ask for a writeable callback on the outgoing connection.
-	 * In the writable callback he can check the flag and then get
-	 * and drain the waiting incoming data using lws_http_client_read().
-	 * This will use callbacks to LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ
-	 * to get and drain the incoming data, where it should be sent
-	 * back out on the outgoing connection. */
+	/**< This indicates data was received on the HTTP client connection.  It
+	 * does NOT actually drain or provide the data, so if you are doing
+	 * http client, you MUST handle this and call lws_http_client_read().
+	 * Failure to deal with it as in the minimal examples may cause spinning
+	 * around the event loop as it's continuously signalled the same data
+	 * is available for read.  The related minimal examples show how to
+	 * handle it.
+	 *
+	 * It's possible to defer calling lws_http_client_read() if you use
+	 * rx flow control to stop further rx handling on the connection until
+	 * you did deal with it.  But normally you would call it in the handler.
+	 *
+	 * lws_http_client_read() strips any chunked framing and calls back
+	 * with only payload data to LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ.  The
+	 * chunking is the reason this is not just all done in one callback for
+	 * http.
+	 */
 	LWS_CALLBACK_COMPLETED_CLIENT_HTTP			= 47,
 	/**< The client transaction completed... at the moment this
 	 * is the same as closing since transaction pipelining on