Update cowboy_loop manual

doc/src/manual/cowboy_handler.asciidoc

@@ -28,10 +28,10 @@ init(Req, State) -> {ok, Req, State}
 
 terminate(Reason, Req, State) -> ok  %% optional
 
-Req        :: cowboy_req:req()
-State      :: any()
-Reason     :: normal
-            | {crash, error | exit | throw, any()}
+Req    :: cowboy_req:req()
+State  :: any()
+Reason :: normal
+        | {crash, error | exit | throw, any()}
 ----
 
 These two callbacks are common to all handlers.

doc/src/manual/cowboy_loop.asciidoc

@@ -2,85 +2,103 @@
 
 == Name
 
-cowboy_loop - loop handlers
+cowboy_loop - Loop handlers
 
 == Description
 
-The `cowboy_loop` module implements a handler interface for
-long running HTTP connections. It is the recommended interface
-for long polling and server-sent events, amongst others.
+The module `cowboy_loop` defines a callback interface for
+long running HTTP connections.
 
-This module is a sub protocol that defines three callbacks to
-be implemented by handlers. The `init/2` and `terminate/3`
-callbacks are common to all handler types and are documented
-in the manual for the link:cowboy_handler.asciidoc[cowboy_handler] module.
+You should switch to this behavior for long polling,
+server-sent events and similar long-running requests.
 
-The `info/3` callback is specific to loop handlers and will be
-called as many times as necessary until a reply is sent.
+There are generally two usage patterns:
 
-It is highly recommended to return a timeout value from the
-`init/2` callback to ensure that the process is terminated
-when no data has been received during that timespan. The
-default timeout is `infinity`, which should only be used if
-you have alternate means of ending inactive connections.
+* Loop until receiving a specific message, then send
+  a response and stop execution (for example long polling);
 
-== Terminate reasons
+* Or initiate a response in `init/2` and stream the
+  body in `info/3` as necessary (for example server-sent events).
 
-The following values may be received as the terminate reason
-in the optional `terminate/3` callback.
+== Callbacks
 
-normal::
-	The connection was closed normally before switching to the
-	loop sub protocol. This typically happens if an `ok` tuple is
-	returned from the `init/2` callback.
+Loop handlers implement the following interface:
 
-stop::
-	The handler requested to close the connection by returning
-	a `stop` tuple.
+[source,erlang]
+----
+init(Req, State)
+    -> {cowboy_loop, Req, State}
+     | {cowboy_loop, Req, State, hibernate}
+     | {cowboy_loop, Req, State, timeout()}
+     | {cowboy_loop, Req, State, timeout(), hibernate}
 
-timeout::
-	The connection has been closed due to inactivity. The timeout
-	value can be configured from `init/2`. The response sent when
-	this happens is a `204 No Content`.
+info(Info, Req, State)
+    -> {ok, Req, State}
+     | {ok, Req, State, hibernate}
+     | {stop, Req, State}
 
-{crash, Class, Reason}::
-	A crash occurred in the handler. `Class` and `Reason` can be
-	used to obtain more information about the crash. The function
-	`erlang:get_stacktrace/0` can also be called to obtain the
-	stacktrace of the process when the crash occurred.
-
-{error, overflow}::
-	The connection is being closed and the process terminated
-	because the buffer Cowboy uses to keep data sent by the
-	client has reached its maximum. The buffer size can be
-	configured through the environment value `loop_max_buffer`
-	and defaults to 5000 bytes.
-	+
-	If the long running request comes with a body it is recommended
-	to process this body before switching to the loop sub protocol.
-
-{error, closed}::
-	The socket has been closed brutally without a close frame being
-	received first.
-
-{error, Reason}::
-	A socket error ocurred.
+terminate(Reason, Req, State) -> ok  %% optional
 
-== Callbacks
+Req    :: cowboy_req:req()
+State  :: any()
+Info   :: any()
+Reason :: stop | timeout
+        | {crash, error | exit | throw, any()}
+----
 
-=== info(Info, Req, State) -> {ok, Req, State} | {ok, Req, State, hibernate} | {stop, Req, State}
+The `init/2` callback is common to all handlers. To switch
+to the loop behavior, it must return `cowboy_loop` as the
+first element of the tuple.
 
-Info = any():: Message received by the process.
-Req = cowboy_req:req():: The Req object.
-State = any():: Handler state.
+The `info/3` callback will be called for every Erlang message
+received. It may choose to continue the receive loop or stop
+it.
 
-Handle the Erlang message received.
+The optional `terminate/3` callback will ultimately be called
+with the reason for the termination of the handler.
+Cowboy will terminate the process right after this. There
+is no need to perform any cleanup in this callback.
 
-This function will be called every time an Erlang message
-has been received. The message can be any Erlang term.
+The following terminate reasons are defined for loop handlers:
 
-The `stop` return value can be used to stop the receive loop,
-typically because a response has been sent.
+stop::
+    The handler requested to close the connection by returning
+    a `stop` tuple.
+
+timeout::
+    The connection has been closed due to inactivity. The timeout
+    value can be configured from `init/2`. The response sent when
+    this happens is a `204 No Content`.
 
-The `hibernate` option will hibernate the process until
-it receives another message.
+{crash, Class, Reason}::
+    A crash occurred in the handler. `Class` and `Reason` can be
+    used to obtain more information about the crash. The function
+    `erlang:get_stacktrace/0` can also be called to obtain the
+    stacktrace of the process when the crash occurred.
+
+//{error, overflow}::
+//    The connection is being closed and the process terminated
+//    because the buffer Cowboy uses to keep data sent by the
+//    client has reached its maximum. The buffer size can be
+//    configured through the environment value `loop_max_buffer`
+//    and defaults to 5000 bytes.
+//    +
+//    If the long running request comes with a body it is recommended
+//    to process this body before switching to the loop sub protocol.
+//
+//{error, closed}::
+//    The socket has been closed brutally without a close frame being
+//    received first.
+//
+//{error, Reason}::
+//    A socket error ocurred.
+
+== Changelog
+
+* *2.0*: Cowboy temporarily no longer checks the socket for data with HTTP/1.1.
+* *1.0*: Behavior introduced.
+
+== See also
+
+link:man:cowboy(7)[cowboy(7)],
+link:man:cowboy_handler(3)[cowboy_handler(3)]

doc/src/manual/cowboy_websocket.asciidoc

@@ -161,5 +161,6 @@ timeout::
 == See also
 
 link:man:cowboy(7)[cowboy(7)],
+link:man:cowboy_handler(3)[cowboy_handler(3)],
 link:man:cowboy_http(3)[cowboy_http(3)],
 link:man:cowboy_http2(3)[cowboy_http2(3)]