docs: add mising CALLBACK docs and some extra info

https://github.com/warmcat/libwebsockets/issues/1015

README.coding.md

@@ -1,6 +1,24 @@
 Notes about coding with lws
 ===========================
 
+@section era Old lws and lws v2.0
+
+Originally lws only supported the "manual" method of handling everything in the
+user callback found in test-server.c.
+
+Since v2.0, the need for most or all of this manual boilerplate has been eliminated:
+the protocols[0] http stuff is provided by a lib export `lws_callback_http_dummy()`.
+You can serve parts of your filesystem at part of the URL space using mounts.
+
+It's much preferred to use the "automated" v2.0 type scheme, because it's less
+code and it's easier to support.
+
+You can see an example of the new way in test-server-v2.0.c.
+
+If you just need generic serving capability, consider not writing any server code
+and instead use lwsws and writing your user code in a standalone plugin.  The
+server is configured for mounts etc using JSON, see README.lwsws.md.
+
 @section dae Daemonization
 
 There's a helper api `lws_daemonize` built by default that does everything you
@@ -902,6 +920,15 @@ This allocation is only deleted / replaced when the connection accesses a
 URL region with a different protocol (or the default protocols[0] if no
 CALLBACK area matches it).
 
+This "binding connection to a protocol" lifecycle in managed by
+`LWS_CALLBACK_HTTP_BIND_PROTOCOL` and `LWS_CALLBACK_HTTP_DROP_PROTOCOL`.
+Because of HTTP/1.1 connection pipelining, one connection may perform
+many transactions, each of which may map to different URLs and need
+binding to different protocols.  So these messages are used to
+create the binding of the wsi to your protocol including any
+allocations, and to destroy the binding, at which point you should
+destroy any related allocations.
+
 @section BINDTODEV SO_BIND_TO_DEVICE
 
 The .bind_iface flag in the context / vhost creation struct lets you

lib/libwebsockets.h

@@ -1188,45 +1188,110 @@ enum lws_callback_reasons {
 	 * connection. */
 
 	LWS_CALLBACK_WS_EXT_DEFAULTS				= 39,
-	/**<  */
+	/**< Gives client connections an opportunity to adjust negotiated
+	 * extension defaults.  `user` is the extension name that was
+	 * negotiated (eg, "permessage-deflate").  `in` points to a
+	 * buffer and `len` is the buffer size.  The user callback can
+	 * set the buffer to a string describing options the extension
+	 * should parse.  Or just ignore for defaults. */
 
 	LWS_CALLBACK_CGI					= 40,
-	/**<  */
+	/**< CGI: CGI IO events on stdin / out / err are sent here on
+	 * protocols[0].  The provided `lws_callback_http_dummy()`
+	 * handles this and the callback should be directed there if
+	 * you use CGI. */
 	LWS_CALLBACK_CGI_TERMINATED				= 41,
-	/**<  */
+	/**< CGI: The related CGI process ended, this is called before
+	 * the wsi is closed.  Used to, eg, terminate chunking.
+	 * The provided `lws_callback_http_dummy()`
+	 * handles this and the callback should be directed there if
+	 * you use CGI. */
 	LWS_CALLBACK_CGI_STDIN_DATA				= 42,
-	/**<  */
+	/**< CGI: Data is, to be sent to the CGI process stdin, eg from
+	 * a POST body.  The provided `lws_callback_http_dummy()`
+	 * handles this and the callback should be directed there if
+	 * you use CGI. */
 	LWS_CALLBACK_CGI_STDIN_COMPLETED			= 43,
-	/**<  */
+	/**< CGI: no more stdin is coming.  The provided
+	 * `lws_callback_http_dummy()` handles this and the callback
+	 * should be directed there if you use CGI. */
 	LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP			= 44,
-	/**<  */
+	/**< The HTTP client connection has succeeded, and is now
+	 * connected to the server */
 	LWS_CALLBACK_CLOSED_CLIENT_HTTP				= 45,
-	/**<  */
+	/**< The HTTP client connection is closing */
 	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. */
 	LWS_CALLBACK_COMPLETED_CLIENT_HTTP			= 47,
-	/**<  */
+	/**< The client transaction completed... at the moment this
+	 * is the same as closing since transaction pipelining on
+	 * client side is not yet supported.  */
 	LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ			= 48,
-	/**<  */
+	/**< This is generated by lws_http_client_read() used to drain
+	 * incoming data.  In the case the incoming data was chunked,
+	 * it will be split into multiple smaller callbacks for each
+	 * chunk block, removing the chunk headers. If not chunked,
+	 * it will appear all in one callback. */
 	LWS_CALLBACK_HTTP_BIND_PROTOCOL				= 49,
-	/**<  */
+	/**< By default, all HTTP handling is done in protocols[0].
+	 * However you can bind different protocols (by name) to
+	 * different parts of the URL space using callback mounts.  This
+	 * callback occurs in the new protocol when a wsi is bound
+	 * to that protocol.  Any protocol allocation related to the
+	 * http transaction processing should be created then.
+	 * These specific callbacks are necessary because with HTTP/1.1,
+	 * a single connection may perform at series of different
+	 * transactions at different URLs, thus the lifetime of the
+	 * protocol bind is just for one transaction, not connection. */
 	LWS_CALLBACK_HTTP_DROP_PROTOCOL				= 50,
-	/**<  */
+	/**< This is called when a transaction is unbound from a protocol.
+	 * It indicates the connection completed its transaction and may
+	 * do something different now.  Any protocol allocation related
+	 * to the http transaction processing should be destroyed. */
 	LWS_CALLBACK_CHECK_ACCESS_RIGHTS			= 51,
-	/**<  */
+	/**< This gives the user code a chance to forbid an http access.
+	 * `in` points to a `struct lws_process_html_args`, which
+	 * describes the URL, and a bit mask describing the type of
+	 * authentication required.  If the callback returns nonzero,
+	 * the transaction ends with HTTP_STATUS_UNAUTHORIZED. */
 	LWS_CALLBACK_PROCESS_HTML				= 52,
-	/**<  */
+	/**< This gives your user code a chance to mangle outgoing
+	 * HTML.  `in` points to a `struct lws_process_html_args`
+	 * which describes the buffer containing outgoing HTML.
+	 * The buffer may grow up to `.max_len` (currently +128
+	 * bytes per buffer).
+	 *  */
 	LWS_CALLBACK_ADD_HEADERS				= 53,
-	/**<  */
+	/**< This gives your user code a chance to add headers to a
+	 * transaction bound to your protocol.  `in` points to a
+	 * `struct lws_process_html_args` you can add headers into
+	 * using the normal lws apis.  See generic sessions for an
+	 * example of how to use with cookies. */
 	LWS_CALLBACK_SESSION_INFO				= 54,
-	/**<  */
+	/**< This is only generated by user code using generic sessions.
+	 * It's used to get a `struct lws_session_info` filled in by
+	 * generic sessions with information about the logged-in user.
+	 * See the messageboard sample for an example of how to use. */
 
 	LWS_CALLBACK_GS_EVENT					= 55,
-	/**<  */
+	/**< Indicates an event happened to the Generic Sessions session.
+	 * `in` contains a `struct lws_gs_event_args` describing the event. */
 	LWS_CALLBACK_HTTP_PMO					= 56,
 	/**< per-mount options for this connection, called before
 	 * the normal LWS_CALLBACK_HTTP when the mount has per-mount
-	 * options
+	 * options.
 	 */
 	LWS_CALLBACK_CLIENT_HTTP_WRITEABLE			= 57,
 	/**< when doing an HTTP type client connection, you can call