Documentation work

CHANGELOG.md

@@ -1,3 +1,7 @@
+Version 49
+
+--------------------------------------------------------------------------------
+
 Version 48
 
 * Make buffer_prefix_view public

doc/0_main.qbk

@@ -79,6 +79,11 @@ asynchronous model of __Asio__.
   ][
     An explanation of requirements, audience, features, and credits.
   ]]
+  [[
+    [link beast.example Examples]
+  ][
+    Examples that illustrate usage for typical scenarios.
+  ]]
   [[
     [link beast.core Core Concepts]
   ][
@@ -94,11 +99,6 @@ asynchronous model of __Asio__.
   ][
     How to use the WebSocket interfaces in your applications.
   ]]
-  [[
-    [link beast.example Examples]
-  ][
-    Examples that illustrate usage for typical scenarios.
-  ]]
   [[
     [link beast.design Design]
   ][
@@ -117,10 +117,10 @@ asynchronous model of __Asio__.
 ]
 
 [include 1_overview.qbk]
-[include 2_0_core.qbk]
+[include 2_examples.qbk]
-[include 3_0_http.qbk]
+[include 3_0_core.qbk]
-[include 4_0_websocket.qbk]
+[include 4_0_http.qbk]
-[include 5_examples.qbk]
+[include 5_0_websocket.qbk]
 [include 6_0_design.qbk]
 
 [section:ref Reference]

doc/3_0_core.qbk

@@ -44,10 +44,10 @@ lists these facilities by group, with descriptions.
     ```
 ]
 
-[include 2_1_asio.qbk]
+[include 3_1_asio.qbk]
-[include 2_2_streams.qbk]
+[include 3_2_streams.qbk]
-[include 2_3_buffers.qbk]
+[include 3_3_buffers.qbk]
-[include 2_4_async.qbk]
+[include 3_4_async.qbk]
-[include 2_5_tutorial.qbk]
+[include 3_5_tutorial.qbk]
 
 [endsect]

doc/4_0_http.qbk

@@ -86,14 +86,14 @@ format using __Asio__. Specifically, the library provides:
     ```
 ]
 
-[include 3_1_primer.qbk]
+[include 4_1_primer.qbk]
-[include 3_2_message.qbk]
+[include 4_2_message.qbk]
-[include 3_3_streams.qbk]
+[include 4_3_streams.qbk]
-[include 3_4_serializer_streams.qbk]
+[include 4_4_serializer_streams.qbk]
-[include 3_5_parser_streams.qbk]
+[include 4_5_parser_streams.qbk]
-[include 3_6_serializer_buffers.qbk]
+[include 4_6_serializer_buffers.qbk]
-[include 3_7_parser_buffers.qbk]
+[include 4_7_parser_buffers.qbk]
-[include 3_8_custom_parsers.qbk]
+[include 4_8_custom_parsers.qbk]
-[include 3_9_custom_body.qbk]
+[include 4_9_custom_body.qbk]
 
 [endsect]

doc/5_0_websocket.qbk

@@ -39,12 +39,12 @@ Boost.Asio with a consistent asynchronous model using a modern C++ approach.
     ```
 ]
 
-[include 4_1_streams.qbk]
+[include 5_1_streams.qbk]
-[include 4_2_connect.qbk]
+[include 5_2_connect.qbk]
-[include 4_3_client.qbk]
+[include 5_3_client.qbk]
-[include 4_4_server.qbk]
+[include 5_4_server.qbk]
-[include 4_5_messages.qbk]
+[include 5_5_messages.qbk]
-[include 4_6_control.qbk]
+[include 5_6_control.qbk]
-[include 4_7_notes.qbk]
+[include 5_7_notes.qbk]
 
 [endsect]

include/beast/core/type_traits.hpp

@@ -23,22 +23,29 @@ namespace beast {
 
 /** Determine if `T` meets the requirements of @b ConstBufferSequence.
 
+    Metafunctions are used to perform compile time checking of template
+    types. This type will be `std::true_type` if `T` meets the requirements,
+    else the type will be `std::false_type`. 
+
     @par Example
+
     Use with `static_assert`:
+
     @code
-        template<class ConstBufferSequence>
+    template<class ConstBufferSequence>
-        void f(ConstBufferSequence const& buffers)
+    void f(ConstBufferSequence const& buffers)
-        {
+    {
-            static_assert(is_const_buffer_sequence<ConstBufferSequence>::value,
+        static_assert(is_const_buffer_sequence<ConstBufferSequence>::value,
-                "ConstBufferSequence requirements not met");
+            "ConstBufferSequence requirements not met");
-            ...
+    ...
-        }
     @endcode
-    Use with `std::enable_if`
+
+    Use with `std::enable_if` (SFINAE):
+
     @code
-        template<class ConstBufferSequence>
+    template<class ConstBufferSequence>
-        typename std::enable_if<is_const_buffer_sequence<ConstBufferSequence>::value>::type
+    typename std::enable_if<is_const_buffer_sequence<ConstBufferSequence>::value>::type
-        f(ConstBufferSequence const& buffers);
+    f(ConstBufferSequence const& buffers);
     @endcode
 */
 template<class T>
@@ -53,22 +60,29 @@ struct is_const_buffer_sequence :
 
 /** Determine if `T` meets the requirements of @b MutableBufferSequence.
 
+    Metafunctions are used to perform compile time checking of template
+    types. This type will be `std::true_type` if `T` meets the requirements,
+    else the type will be `std::false_type`. 
+
     @par Example
+
     Use with `static_assert`:
+
     @code
-        template<class MutableBufferSequence>
+    template<class MutableBufferSequence>
-        void f(MutableBufferSequence const& buffers)
+    void f(MutableBufferSequence const& buffers)
-        {
+    {
-            static_assert(is_const_buffer_sequence<MutableBufferSequence>::value,
+        static_assert(is_const_buffer_sequence<MutableBufferSequence>::value,
-                "MutableBufferSequence requirements not met");
+            "MutableBufferSequence requirements not met");
-            ...
+    ...
-        }
     @endcode
-    Use with `std::enable_if`
+
+    Use with `std::enable_if` (SFINAE):
+
     @code
-        template<class MutableBufferSequence>
+    template<class MutableBufferSequence>
-        typename std::enable_if<is_mutable_buffer_sequence<MutableBufferSequence>::value>::type
+    typename std::enable_if<is_mutable_buffer_sequence<MutableBufferSequence>::value>::type
-        f(MutableBufferSequence const& buffers);
+    f(MutableBufferSequence const& buffers);
     @endcode
 */
 template<class T>
@@ -83,22 +97,29 @@ struct is_mutable_buffer_sequence :
 
 /** Determine if `T` meets the requirements of @b DynamicBuffer.
 
+    Metafunctions are used to perform compile time checking of template
+    types. This type will be `std::true_type` if `T` meets the requirements,
+    else the type will be `std::false_type`. 
+
     @par Example
+
     Use with `static_assert`:
+
     @code
-        template<class DynamicBuffer>
+    template<class DynamicBuffer>
-        void f(DynamicBuffer& buffer)
+    void f(DynamicBuffer& buffer)
-        {
+    {
-            static_assert(is_dynamic_buffer<DynamicBuffer>::value,
+        static_assert(is_dynamic_buffer<DynamicBuffer>::value,
-                "DynamicBuffer requirements not met");
+            "DynamicBuffer requirements not met");
-            ...
+    ...
-        }
     @endcode
-    Use with `std::enable_if`
+
+    Use with `std::enable_if` (SFINAE):
+
     @code
-        template<class DynamicBuffer>
+    template<class DynamicBuffer>
-        typename std::enable_if<is_dynamic_buffer<DynamicBuffer>::value>::type
+    typename std::enable_if<is_dynamic_buffer<DynamicBuffer>::value>::type
-        f(DynamicBuffer const& buffer);
+    f(DynamicBuffer const& buffer);
     @endcode
 */
 #if BEAST_DOXYGEN
@@ -149,11 +170,16 @@ struct is_dynamic_buffer<
 
 /** Determine if `T` meets the requirements of @b CompletionHandler.
 
-    This metafunction will be equivalent to `std::true_type` if `T`
+    This trait checks whether a type meets the requirements for a completion
-    meets the requirements for a completion handler callable with
+    handler, and is also callable with the specified signature.
-    the given signature.
+    Metafunctions are used to perform compile time checking of template
+    types. This type will be `std::true_type` if `T` meets the requirements,
+    else the type will be `std::false_type`. 
 
     @par Example
+
+    Use with `static_assert`:
+
     @code
     struct handler
     {
@@ -181,7 +207,36 @@ using is_completion_handler = std::integral_constant<bool,
 
 /** Determine if `T` has the `get_io_service` member.
 
+    Metafunctions are used to perform compile time checking of template
+    types. This type will be `std::true_type` if `T` has the member
+    function with the correct signature, else type will be `std::false_type`. 
+
     @par Example
+
+    Use with tag dispatching:
+
+    @code
+    template<class T>
+    void maybe_hello(T& t, std::true_type)
+    {
+        t.get_io_service().post([]{ std::cout << "Hello, world!" << std::endl; });
+    }
+
+    template<class T>
+    void maybe_hello(T&, std::false_type)
+    {
+        // T does not have get_io_service
+    }
+
+    template<class T>
+    void maybe_hello(T& t)
+    {
+        maybe_hello(t, has_get_io_service<T>{});
+    }
+    @endcode
+
+    Use with `static_assert`:
+
     @code
     struct stream
     {
@@ -208,7 +263,13 @@ struct has_get_io_service<T, beast::detail::void_t<decltype(
 
 /** Returns `T::lowest_layer_type` if it exists, else `T`
 
+    This will contain a nested `type` equal to `T::lowest_layer_type`
+    if it exists, else `type` will be equal to `T`.
+
     @par Example
+
+    Declaring a wrapper:
+
     @code
     template<class Stream>
     struct stream_wrapper
@@ -217,6 +278,15 @@ struct has_get_io_service<T, beast::detail::void_t<decltype(
         using lowest_layer_type = typename get_lowest_layer<stream_type>::type;
     };
     @endcode
+
+    Defining a metafunction:
+
+    @code
+    /// Alias for `std::true_type` if `T` wraps another stream
+    template<class T>
+    using is_stream_wrapper : std::integral_constant<bool,
+        ! std::is_same<T, typename get_lowest_layer<T>::type>::value> {};
+    @endcode
 */
 #if BEAST_DOXYGEN
 template<class T>
@@ -238,18 +308,25 @@ struct get_lowest_layer<T, detail::void_t<
 
 /** Determine if `T` meets the requirements of @b AsyncReadStream.
 
+    Metafunctions are used to perform compile time checking of template
+    types. This type will be `std::true_type` if `T` meets the requirements,
+    else the type will be `std::false_type`. 
+
     @par Example
+    
     Use with `static_assert`:
+    
     @code
-        template<class AsyncReadStream>
+    template<class AsyncReadStream>
-        void f(AsyncReadStream& stream)
+    void f(AsyncReadStream& stream)
-        {
+    {
-            static_assert(is_async_read_stream<AsyncReadStream>::value,
+        static_assert(is_async_read_stream<AsyncReadStream>::value,
-                "AsyncReadStream requirements not met");
+            "AsyncReadStream requirements not met");
-            ...
+    ...
-        }
     @endcode
-    Use with `std::enable_if`
+    
+    Use with `std::enable_if` (SFINAE):
+    
     @code
         template<class AsyncReadStream>
         typename std::enable_if<is_async_read_stream<AsyncReadStream>::value>::type
@@ -275,22 +352,29 @@ struct is_async_read_stream<T, detail::void_t<decltype(
 
 /** Determine if `T` meets the requirements of @b AsyncWriteStream.
 
+    Metafunctions are used to perform compile time checking of template
+    types. This type will be `std::true_type` if `T` meets the requirements,
+    else the type will be `std::false_type`. 
+
     @par Example
+
     Use with `static_assert`:
+
     @code
-        template<class AsyncWriteStream>
+    template<class AsyncWriteStream>
-        void f(AsyncWriteStream& stream)
+    void f(AsyncWriteStream& stream)
-        {
+    {
-            static_assert(is_async_write_stream<AsyncWriteStream>::value,
+        static_assert(is_async_write_stream<AsyncWriteStream>::value,
-                "AsyncWriteStream requirements not met");
+            "AsyncWriteStream requirements not met");
-            ...
+    ...
-        }
     @endcode
-    Use with `std::enable_if`
+
+    Use with `std::enable_if` (SFINAE):
+
     @code
-        template<class AsyncWriteStream>
+    template<class AsyncWriteStream>
-        typename std::enable_if<is_async_write_stream<AsyncWriteStream>::value>::type
+    typename std::enable_if<is_async_write_stream<AsyncWriteStream>::value>::type
-        f(AsyncWriteStream& stream);
+    f(AsyncWriteStream& stream);
     @endcode
 */
 #if BEAST_DOXYGEN
@@ -312,22 +396,29 @@ struct is_async_write_stream<T, detail::void_t<decltype(
 
 /** Determine if `T` meets the requirements of @b SyncReadStream.
 
+    Metafunctions are used to perform compile time checking of template
+    types. This type will be `std::true_type` if `T` meets the requirements,
+    else the type will be `std::false_type`. 
+
     @par Example
+
     Use with `static_assert`:
+
     @code
-        template<class SyncReadStream>
+    template<class SyncReadStream>
-        void f(SyncReadStream& stream)
+    void f(SyncReadStream& stream)
-        {
+    {
-            static_assert(is_sync_read_stream<SyncReadStream>::value,
+        static_assert(is_sync_read_stream<SyncReadStream>::value,
-                "SyncReadStream requirements not met");
+            "SyncReadStream requirements not met");
-            ...
+    ...
-        }
     @endcode
-    Use with `std::enable_if`
+
+    Use with `std::enable_if` (SFINAE):
+
     @code
-        template<class SyncReadStream>
+    template<class SyncReadStream>
-        typename std::enable_if<is_sync_read_stream<SyncReadStream>::value>::type
+    typename std::enable_if<is_sync_read_stream<SyncReadStream>::value>::type
-        f(SyncReadStream& stream);
+    f(SyncReadStream& stream);
     @endcode
 */
 #if BEAST_DOXYGEN
@@ -351,22 +442,29 @@ struct is_sync_read_stream<T, detail::void_t<decltype(
 
 /** Determine if `T` meets the requirements of @b SyncWriterStream.
 
+    Metafunctions are used to perform compile time checking of template
+    types. This type will be `std::true_type` if `T` meets the requirements,
+    else the type will be `std::false_type`. 
+
     @par Example
+
     Use with `static_assert`:
+
     @code
-        template<class SyncReadStream>
+    template<class SyncReadStream>
-        void f(SyncReadStream& stream)
+    void f(SyncReadStream& stream)
-        {
+    {
-            static_assert(is_sync_read_stream<SyncReadStream>::value,
+        static_assert(is_sync_read_stream<SyncReadStream>::value,
-                "SyncReadStream requirements not met");
+            "SyncReadStream requirements not met");
-            ...
+    ...
-        }
     @endcode
-    Use with `std::enable_if`
+
+    Use with `std::enable_if` (SFINAE):
+
     @code
-        template<class SyncReadStream>
+    template<class SyncReadStream>
-        typename std::enable_if<is_sync_read_stream<SyncReadStream>::value>::type
+    typename std::enable_if<is_sync_read_stream<SyncReadStream>::value>::type
-        f(SyncReadStream& stream);
+    f(SyncReadStream& stream);
     @endcode
 */
 #if BEAST_DOXYGEN
@@ -390,22 +488,29 @@ struct is_sync_write_stream<T, detail::void_t<decltype(
 
 /** Determine if `T` meets the requirements of @b AsyncStream.
 
+    Metafunctions are used to perform compile time checking of template
+    types. This type will be `std::true_type` if `T` meets the requirements,
+    else the type will be `std::false_type`. 
+
     @par Example
+
     Use with `static_assert`:
+
     @code
-        template<class AsyncStream>
+    template<class AsyncStream>
-        void f(AsyncStream& stream)
+    void f(AsyncStream& stream)
-        {
+    {
-            static_assert(is_async_stream<AsyncStream>::value,
+        static_assert(is_async_stream<AsyncStream>::value,
-                "AsyncStream requirements not met");
+            "AsyncStream requirements not met");
-            ...
+    ...
-        }
     @endcode
-    Use with `std::enable_if`
+
+    Use with `std::enable_if` (SFINAE):
+
     @code
-        template<class AsyncStream>
+    template<class AsyncStream>
-        typename std::enable_if<is_async_stream<AsyncStream>::value>::type
+    typename std::enable_if<is_async_stream<AsyncStream>::value>::type
-        f(AsyncStream& stream);
+    f(AsyncStream& stream);
     @endcode
 */
 #if BEAST_DOXYGEN
@@ -419,23 +524,29 @@ using is_async_stream = std::integral_constant<bool,
 
 /** Determine if `T` meets the requirements of @b SyncStream.
 
+    Metafunctions are used to perform compile time checking of template
+    types. This type will be `std::true_type` if `T` meets the requirements,
+    else the type will be `std::false_type`. 
 
     @par Example
+
     Use with `static_assert`:
+
     @code
-        template<class SyncStream>
+    template<class SyncStream>
-        void f(SyncStream& stream)
+    void f(SyncStream& stream)
-        {
+    {
-            static_assert(is_sync_stream<SyncStream>::value,
+        static_assert(is_sync_stream<SyncStream>::value,
-                "SyncStream requirements not met");
+            "SyncStream requirements not met");
-            ...
+    ...
-        }
     @endcode
-    Use with `std::enable_if`
+
+    Use with `std::enable_if` (SFINAE):
+
     @code
-        template<class SyncStream>
+    template<class SyncStream>
-        typename std::enable_if<is_sync_stream<SyncStream>::value>::type
+    typename std::enable_if<is_sync_stream<SyncStream>::value>::type
-        f(SyncStream& stream);
+    f(SyncStream& stream);
     @endcode
 */
 #if BEAST_DOXYGEN