Fix more documentation todos

I have decided not to include a manual page for
cowboy_stream_h at this point because it clashes
with the cowboy_stream manual page. This decision
will be revisited in the future.

doc/src/guide/book.asciidoc

@@ -75,6 +75,4 @@ include::middlewares.asciidoc[Middlewares]
 
 include::migrating_from_1.0.asciidoc[Migrating from Cowboy 1.0 to 2.0]
 
-// @todo Maybe history? Could take info from architecture also.
-
 include::specs.asciidoc[HTTP and other specifications]

doc/src/guide/loop_handlers.asciidoc

@@ -1,8 +1,6 @@
 [[loop_handlers]]
 == Loop handlers
 
-// @todo This description needs to be updated.
-
 Loop handlers are a special kind of HTTP handlers used when the
 response can not be sent right away. The handler enters instead
 a receive loop waiting for the right message before it can send

doc/src/guide/modern_web.asciidoc

@@ -1,8 +1,6 @@
 [[modern_web]]
 == The modern Web
 
-// @todo Link to related xrefs.
-
 Cowboy is a server for the modern Web. This chapter explains
 what it means and details all the standards involved.
 
@@ -56,9 +54,9 @@ methods, status codes, headers or semantics.
 
 === Websocket
 
-Websocket is a protocol built on top of HTTP/1.1 that provides
+xref:ws_protocol[Websocket] is a protocol built on top of HTTP/1.1
-a two-ways communication channel between the client and the
+that provides a two-ways communication channel between the client and
-server. Communication is asynchronous and can occur concurrently.
+the server. Communication is asynchronous and can occur concurrently.
 
 It consists of a Javascript object allowing setting up a
 Websocket connection to the server, and a binary based
@@ -79,6 +77,9 @@ is closer to TCP in that aspect, and requires you to design
 and implement your own protocol on top of it; or adapt an
 existing protocol to Websocket.
 
+Cowboy provides an interface known as xref:ws_handlers[Websocket handlers]
+that gives complete control over a Websocket connection.
+
 The Websocket protocol is defined by RFC 6455.
 
 === Long-lived requests
@@ -101,21 +102,21 @@ type, `text/event-stream`, along with a new HTTP header,
 `Last-Event-ID`. It is defined in the EventSource W3C
 specification.
 
-Cowboy provides an interface known as loop handlers that
+Cowboy provides an interface known as xref:loop_handlers[loop handlers]
-facilitates the implementation of long-polling or stream
+that facilitates the implementation of long-polling or stream
 mechanisms. It works regardless of the underlying protocol.
 
 === REST
 
-REST, or REpresentational State Transfer, is a style of
+xref:rest_principles[REST, or REpresentational State Transfer],
-architecture for loosely connected distributed systems.
+is a style of architecture for loosely connected distributed
-It can easily be implemented on top of HTTP.
+systems. It can easily be implemented on top of HTTP.
 
 REST is essentially a set of constraints to be followed.
 Many of these constraints are purely architectural and
 solved by simply using HTTP. Some constraints must be
 explicitly followed by the developer.
 
-Cowboy provides an interface known as REST handlers that
+Cowboy provides an interface known as xref:rest_handlers[REST handlers]
-simplifies the implementation of a REST API on top of
+that simplifies the implementation of a REST API on top of
 the HTTP protocol.

doc/src/guide/ws_handlers.asciidoc

@@ -151,7 +151,9 @@ websocket_info(_Info, State) ->
 
 === Sending frames
 
-// @todo So yeah, reply makes no sense. Maybe change it to send. Sigh.
+// @todo This will be deprecated and eventually replaced with a
+// {Commands, State} interface that allows providing more
+// functionality easily.
 
 All `websocket_` callbacks share return values. They may
 send zero, one or many frames to the client.
@@ -222,8 +224,6 @@ init(Req, State) ->
 This value cannot be changed once it is set. It defaults to
 `60000`.
 
-// @todo Perhaps the default should be changed.
-
 === Saving memory
 
 The Websocket connection process can be set to hibernate

doc/src/manual/cowboy.start_clear.asciidoc

@@ -47,16 +47,12 @@ ProtocolOpts::
 
 The protocol options are in a map containing all the options for
 the different protocols that may be involved when connecting
-to the listener, including HTTP/1.1 and HTTP/2 but also
+to the listener, including HTTP/1.1 and HTTP/2.
-subprotocols like Websocket.
-// @todo For Websocket this might change in the future.
 +
 The HTTP/1.1 options are documented in the
 link:man:cowboy_http(3)[cowboy_http(3)] manual;
-the HTTP/2 options in
+and the HTTP/2 options in
-link:man:cowboy_http2(3)[cowboy_http2(3)];
+link:man:cowboy_http2(3)[cowboy_http2(3)].
-and the Websocket options in
-link:man:cowboy_websocket(3)[cowboy_websocket(3)].
 
 == Return value
 

doc/src/manual/cowboy.start_tls.asciidoc

@@ -47,16 +47,12 @@ ProtocolOpts::
 
 The protocol options are in a map containing all the options for
 the different protocols that may be involved when connecting
-to the listener, including HTTP/1.1 and HTTP/2 but also
+to the listener, including HTTP/1.1 and HTTP/2.
-subprotocols like Websocket.
-// @todo For Websocket this might change in the future.
 +
 The HTTP/1.1 options are documented in the
 link:man:cowboy_http(3)[cowboy_http(3)] manual;
-the HTTP/2 options in
+and the HTTP/2 options in
-link:man:cowboy_http2(3)[cowboy_http2(3)];
+link:man:cowboy_http2(3)[cowboy_http2(3)].
-and the Websocket options in
-link:man:cowboy_websocket(3)[cowboy_websocket(3)].
 
 == Return value
 

doc/src/manual/cowboy_app.asciidoc

@@ -20,8 +20,7 @@ Functions:
 * link:man:cowboy(3)[cowboy(3)] - Listener management
 * link:man:cowboy_req(3)[cowboy_req(3)] - Request and response
 * link:man:cowboy_router(3)[cowboy_router(3)] - Router
-
+* link:man:cowboy_constraints(3)[cowboy_constraints(3)] - Constraints
-// @todo What about cowboy_constraints?
 
 Protocols:
 
@@ -33,9 +32,6 @@ Handlers:
 
 * link:man:cowboy_static(3)[cowboy_static(3)] - Static file handler
 
-// @todo What about cowboy_stream_h?
-// @todo cowboy_compress_h
-
 Behaviors:
 
 * link:man:cowboy_handler(3)[cowboy_handler(3)] - Plain HTTP handlers

doc/src/manual/cowboy_constraints.asciidoc

@@ -0,0 +1,60 @@
+= cowboy_constraints(3)
+
+== Name
+
+cowboy_constraints - Constraints
+
+== Description
+
+The module `cowboy_constraints` defines the built-in
+constraints in Cowboy and provides an interface for
+manipulating these constraints.
+
+Constraints are functions that define what type of
+input is allowed. They are used throughout Cowboy,
+from the router to query strings to cookies.
+
+== Exports
+
+Built-in constraints:
+
+* link:man:cowboy_constraints:int(3)[cowboy_constraints:int(3)] - Integer constraint
+* link:man:cowboy_constraints:nonempty(3)[cowboy_constraints:nonempty(3)] - Non-empty constraint
+
+== Types
+
+=== constraint()
+
+[source,erlang]
+----
+constraint() :: int | nonempty | fun()
+----
+
+A constraint function.
+
+The atom constraints are built-in, see the corresponding
+function in the exports list above.
+
+=== reason()
+
+[source,erlang]
+----
+reason() :: {constraint(), Reason, Value}
+
+Reason :: any()
+Value  :: any()
+----
+
+Reason for the constraint failure.
+
+It includes the constraint function in question,
+a machine-readable error reason and the value that
+made the constraint fail.
+
+== See also
+
+link:man:cowboy(7)[cowboy(7)],
+link:man:cowboy(3)[cowboy(3)],
+link:man:cowboy_router(3)[cowboy_router(3)],
+link:man:cowboy_req:match_cookies(3)[cowboy_req:match_cookies(3)],
+link:man:cowboy_req:match_qs(3)[cowboy_req:match_qs(3)]

doc/src/manual/cowboy_constraints.int.asciidoc

@@ -0,0 +1,63 @@
+= cowboy_constraints:int(3)
+
+== Name
+
+cowboy_constraints:int - Integer constraint
+
+== Description
+
+Constraint functions implement a number of different operations.
+
+[source,erlang]
+----
+int(forward, Bin) -> {ok, Int} | {error, not_an_integer}
+
+Bin :: binary()
+Int :: integer()
+----
+
+Validate and convert the text representation of an integer.
+
+[source,erlang]
+----
+int(reverse, Int) -> {ok, Bin} | {error, not_an_integer}
+----
+
+Convert an integer back to its text representation.
+
+[source,erlang]
+----
+int(format_error, Error) -> HumanReadable
+
+Error         :: {not_an_integer, Bin | Int}
+HumanReadable :: iolist()
+----
+
+Generate a human-readable error message.
+
+== Arguments
+
+Arguments vary depending on the operation. Constraint
+functions always take the operation type as first argument,
+and the value as second argument.
+
+== Return value
+
+The return value varies depending on the operation.
+
+== Changelog
+
+* *2.0*: Interface modified to allow for a variety of operations.
+* *1.0*: Constraint introduced.
+
+== Examples
+
+This function is not meant to be called directly.
+
+== See also
+
+link:man:cowboy_constraints(3)[cowboy_constraints(3)],
+link:man:cowboy_constraints:nonempty(3)[cowboy_constraints:nonempty(3)],
+link:man:cowboy_router(3)[cowboy_router(3)],
+link:man:cowboy_req:match_cookies(3)[cowboy_req:match_cookies(3)],
+link:man:cowboy_req:match_qs(3)[cowboy_req:match_qs(3)]

doc/src/manual/cowboy_constraints.nonempty.asciidoc

@@ -0,0 +1,62 @@
+= cowboy_constraints:nonempty(3)
+
+== Name
+
+cowboy_constraints:nonempty - Non-empty constraint
+
+== Description
+
+Constraint functions implement a number of different operations.
+
+[source,erlang]
+----
+nonempty(forward | reverse, <<>>) -> {error, empty}
+----
+
+Reject empty values.
+
+[source,erlang]
+----
+nonempty(forward | reverse, Bin) -> {ok, Bin}
+
+Bin :: binary()
+----
+
+Accept any other binary values.
+
+[source,erlang]
+----
+nonempty(format_error, Error) -> HumanReadable
+
+Error         :: {empty, Bin}
+HumanReadable :: iolist()
+----
+
+Generate a human-readable error message.
+
+== Arguments
+
+Arguments vary depending on the operation. Constraint
+functions always take the operation type as first argument,
+and the value as second argument.
+
+== Return value
+
+The return value varies depending on the operation.
+
+== Changelog
+
+* *2.0*: Interface modified to allow for a variety of operations.
+* *1.0*: Constraint introduced.
+
+== Examples
+
+This function is not meant to be called directly.
+
+== See also
+
+link:man:cowboy_constraints(3)[cowboy_constraints(3)],
+link:man:cowboy_constraints:int(3)[cowboy_constraints:int(3)],
+link:man:cowboy_router(3)[cowboy_router(3)],
+link:man:cowboy_req:match_cookies(3)[cowboy_req:match_cookies(3)],
+link:man:cowboy_req:match_qs(3)[cowboy_req:match_qs(3)]

doc/src/manual/cowboy_handler.terminate.asciidoc

@@ -8,12 +8,12 @@ cowboy_handler:terminate - Terminate the handler
 
 [source,erlang]
 ----
-terminate(Reason, Req | undefined, State, Handler) -> ok
+terminate(Reason, PartialReq, State, Handler) -> ok
 
-Reason  :: any()
+Reason     :: any()
-Req     :: cowboy_req:req()
+PartialReq :: map()
-State   :: any()
+State      :: any()
-Handler :: module()
+Handler    :: module()
 ----
 
 Call the optional terminate callback if it is defined.
@@ -27,13 +27,13 @@ Reason::
 
 Reason for termination.
 
-Req::
+PartialReq::
 
 The Req object.
 +
-It is possible to pass `undefined` if the handler has no concept
+It is possible to remove fields from the Req object to save memory
-of requests/responses and discarded the Req object before calling
+when the handler has no concept of requests/responses. The only
-this function.
+requirement is that a map is provided.
 
 State::
 

doc/src/manual/cowboy_websocket.asciidoc

@@ -25,9 +25,10 @@ websocket_init(State)            -> CallResult  %% optional
 websocket_handle(InFrame, State) -> CallResult
 websocket_info(Info, State)      -> CallResult
 
-terminate(Reason, undefined, State) -> ok       %% optional
+terminate(Reason, PartialReq, State) -> ok      %% optional
 
 Req        :: cowboy_req:req()
+PartialReq :: map()
 State      :: any()
 Opts       :: cowboy_websocket:opts()
 InFrame    :: {text | binary | ping | pong, binary()}
@@ -74,9 +75,8 @@ tuple).
 
 The optional `terminate/3` callback will ultimately be called
 with the reason for the termination of the connection. This
-callback is common to all handlers. Note that Websocket has
+callback is common to all handlers. Note that Websocket will
-no concept of requests so it sets the second argument to
+not provide the full Req object by default, to save memory.
-undefined.
 
 Cowboy will terminate the process right after closing the
 Websocket connection. This means that there is no need to

src/cowboy_constraints.erl

@@ -78,11 +78,11 @@ int(format_error, {not_an_integer, Value}) ->
 	io_lib:format("The value ~p is not an integer.", [Value]).
 
 nonempty(Type, <<>>) when Type =/= format_error ->
-	{error, not_empty};
+	{error, empty};
 nonempty(Type, Value) when Type =/= format_error, is_binary(Value) ->
 	{ok, Value};
-nonempty(format_error, {not_empty, Value}) ->
+nonempty(format_error, {empty, Value}) ->
-	io_lib:format("The value ~p is not empty.", [Value]).
+	io_lib:format("The value ~p is empty.", [Value]).
 
 -ifdef(TEST).
 

src/cowboy_handler.erl

@@ -28,7 +28,7 @@
 	| {module(), Req, any(), any()}
 	when Req::cowboy_req:req().
 
--callback terminate(any(), cowboy_req:req(), any()) -> ok.
+-callback terminate(any(), map(), any()) -> ok.
 -optional_callbacks([terminate/3]).
 
 -spec execute(Req, Env) -> {ok, Req, Env}