Refactor docs

include/boost/beast/core/basic_stream.hpp

@@ -42,19 +42,22 @@ template<typename> class stream;
 namespace boost {
 namespace beast {
 
-/** A stream socket wrapper with timeouts, bandwidth limits, and associated executor.
+/** A stream socket wrapper with timeouts, an executor, and a rate limit policy.
 
     This stream wraps a `net::basic_stream_socket` to provide
     the following features:
 
-    @li Optional timeouts may be specified for each logical asynchronous
-    operation performing any reading, writing, or connecting.
-
     @li An <em>Executor</em> may be associated with the stream, which will
     be used to invoke any completion handlers which do not already have
     an associated executor. This achieves support for
     <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1322r0.html">[P1322R0] Networking TS enhancement to enable custom I/O executors</a>.
 
+    @li Timeouts may be specified for each logical asynchronous operation
+    performing any reading, writing, or connecting.
+
+    @li A <em>RatePolicy</em> may be associated with the stream, to implement
+    rate limiting through the policy's interface.
+
     Although the stream supports multiple concurrent outstanding asynchronous
     operations, the stream object is not thread-safe. The caller is responsible
     for ensuring that the stream is accessed from only one thread at a time.

include/boost/beast/core/rate_policy.hpp

@@ -91,14 +91,13 @@ private:
 
 /** A rate policy with unlimited throughput.
 
-    This rate policy places no restrictions on read and write
-    bandwidth utilization.
+    This rate policy object does not apply any rate limit.
 
     @par Concepts
 
     @li <em>RatePolicy</em>
 
-    @see @ref beast::basic_stream
+    @see beast::basic_stream, beast::tcp_stream
 */
 class unlimited_rate_policy
 {
@@ -137,7 +136,7 @@ class unlimited_rate_policy
 
 //------------------------------------------------------------------------------
 
-/** A rate policy with simple, configurable limits on read and write throughput.
+/** A rate policy with simple, configurable limits on reads and writes.
 
     This rate policy allows for simple individual limits on the amount
     of bytes per second allowed for reads and writes.

include/boost/beast/core/tcp_stream.hpp

@@ -12,17 +12,21 @@
 
 #include <boost/beast/core/detail/config.hpp>
 #include <boost/beast/core/basic_stream.hpp>
+#include <boost/beast/core/rate_policy.hpp>
 #include <boost/asio/executor.hpp>
 #include <boost/asio/ip/tcp.hpp>
 
 namespace boost {
 namespace beast {
 
-/** A TCP/IP stream socket with timeouts, rate limits, and polymorphic executor.
+/** A TCP/IP stream socket with timeouts and a polymorphic executor.
 
     @see basic_stream
 */
-using tcp_stream = basic_stream<net::ip::tcp, net::executor>;
+using tcp_stream = basic_stream<
+    net::ip::tcp,
+    net::executor,
+    unlimited_rate_policy>;
 
 } // beast
 } // boost