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
-a two-ways communication channel between the client and the
-server. Communication is asynchronous and can occur concurrently.
+xref:ws_protocol[Websocket] is a protocol built on top of HTTP/1.1
+that provides a two-ways communication channel between the client and
+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
-facilitates the implementation of long-polling or stream
+Cowboy provides an interface known as xref:loop_handlers[loop handlers]
+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
-architecture for loosely connected distributed systems.
-It can easily be implemented on top of HTTP.
+xref:rest_principles[REST, or REpresentational State Transfer],
+is a style of architecture for loosely connected distributed
+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
-simplifies the implementation of a REST API on top of
+Cowboy provides an interface known as xref:rest_handlers[REST handlers]
+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