Doc tidying

fix #521, fix #524

include/beast/core/async_result.hpp

@@ -32,7 +32,7 @@ namespace beast {
     where the specific completion handler signature is known.
 
     This template takes advantage of specializations of both
-    `boost::asio_async_result` and `boost::asio::handler_type` for user-defined
+    `boost::asio::async_result` and `boost::asio::handler_type` for user-defined
     completion token types. The primary template assumes that the
     @b CompletionToken is the completion handler.
 

include/beast/core/drain_buffer.hpp

@@ -42,6 +42,7 @@ public:
     /// Copy constructor
     drain_buffer(drain_buffer const&)
     {
+        // Previously returned ranges are invalidated
     }
 
     /// Copy assignment

include/beast/http/fields.hpp

@@ -35,10 +35,10 @@ namespace http {
     value.
 
     Field names are stored as-is, but comparisons are case-insensitive.
-    When the container is iterated, the fields are presented in the order
-    of insertion. For fields with the same name, the container behaves
-    as a `std::multiset`; there will be a separate value for each occurrence
-    of the field name.
+    The container behaves as a `std::multiset`; there will be a separate
+    value for each occurrence of the same field name. When the container
+    is iterated the fields are presented in the order of insertion, with
+    fields having the same name following each other consecutively.
 
     Meets the requirements of @b Fields
 

include/beast/http/message.hpp

@@ -53,7 +53,7 @@ struct header<true, Fields> : Fields
 
     /// Indicates if the header is a request or response.
 #if BEAST_DOXYGEN
-    using is_request = isRequest;
+    using is_request = std::integral_constant<bool, isRequest>;
 #else
     using is_request = std::true_type;
 #endif
@@ -203,7 +203,11 @@ struct header<false, Fields> : Fields
         "Fields requirements not met");
 
     /// Indicates if the header is a request or response.
+#if BEAST_DOXYGEN
+    using is_request = std::integral_constant<bool, isRequest>;
+#else
     using is_request = std::false_type;
+#endif
 
     /// The type representing the fields.
     using fields_type = Fields;

include/beast/websocket/impl/write.ipp

@@ -546,27 +546,120 @@ upcall:
     d_.invoke(ec);
 }
 
+//------------------------------------------------------------------------------
+
 template<class NextLayer>
-template<class ConstBufferSequence, class WriteHandler>
-async_return_type<
-    WriteHandler, void(error_code)>
-stream<NextLayer>::
-async_write_frame(bool fin,
-    ConstBufferSequence const& bs, WriteHandler&& handler)
+template<class Buffers, class Handler>
+class stream<NextLayer>::write_op
 {
-    static_assert(is_async_stream<next_layer_type>::value,
-        "AsyncStream requirements not met");
-    static_assert(beast::is_const_buffer_sequence<
-        ConstBufferSequence>::value,
-            "ConstBufferSequence requirements not met");
-    async_completion<WriteHandler,
-        void(error_code)> init{handler};
-    write_frame_op<ConstBufferSequence, handler_type<
-        WriteHandler, void(error_code)>>{init.completion_handler,
-            *this, fin, bs};
-    return init.result.get();
+    struct data : op
+    {
+        int step = 0;
+        stream<NextLayer>& ws;
+        consuming_buffers<Buffers> cb;
+        std::size_t remain;
+
+        data(Handler& handler, stream<NextLayer>& ws_,
+                Buffers const& bs)
+            : ws(ws_)
+            , cb(bs)
+            , remain(boost::asio::buffer_size(cb))
+        {
+        }
+    };
+
+    handler_ptr<data, Handler> d_;
+
+public:
+    write_op(write_op&&) = default;
+    write_op(write_op const&) = default;
+
+    template<class DeducedHandler, class... Args>
+    explicit
+    write_op(DeducedHandler&& h,
+            stream<NextLayer>& ws, Args&&... args)
+        : d_(std::forward<DeducedHandler>(h),
+            ws, std::forward<Args>(args)...)
+    {
+    }
+
+    void operator()(error_code ec);
+
+    friend
+    void* asio_handler_allocate(
+        std::size_t size, write_op* op)
+    {
+        using boost::asio::asio_handler_allocate;
+        return asio_handler_allocate(
+            size, std::addressof(op->d_.handler()));
+    }
+
+    friend
+    void asio_handler_deallocate(
+        void* p, std::size_t size, write_op* op)
+    {
+        using boost::asio::asio_handler_deallocate;
+        asio_handler_deallocate(
+            p, size, std::addressof(op->d_.handler()));
+    }
+
+    friend
+    bool asio_handler_is_continuation(write_op* op)
+    {
+        using boost::asio::asio_handler_is_continuation;
+        return op->d_->step > 2 ||
+            asio_handler_is_continuation(
+                std::addressof(op->d_.handler()));
+    }
+
+    template<class Function>
+    friend
+    void asio_handler_invoke(Function&& f, write_op* op)
+    {
+        using boost::asio::asio_handler_invoke;
+        asio_handler_invoke(
+            f, std::addressof(op->d_.handler()));
+    }
+};
+
+template<class NextLayer>
+template<class Buffers, class Handler>
+void
+stream<NextLayer>::
+write_op<Buffers, Handler>::
+operator()(error_code ec)
+{
+    auto& d = *d_;
+    switch(d.step)
+    {
+    case 2:
+        d.step = 3;
+        BOOST_FALLTHROUGH;
+    case 3:
+    case 0:
+    {
+        auto const n = d.remain;
+        d.remain -= n;
+        auto const fin = d.remain <= 0;
+        if(fin)
+            d.step = d.step ? 4 : 1;
+        else
+            d.step = d.step ? 3 : 2;
+        auto const pb = buffer_prefix(n, d.cb);
+        d.cb.consume(n);
+        return d.ws.async_write_frame(
+            fin, pb, std::move(*this));
+    }
+
+    case 1:
+    case 4:
+        break;
+    }
+    d_.invoke(ec);
 }
 
+//------------------------------------------------------------------------------
+
 template<class NextLayer>
 template<class ConstBufferSequence>
 void
@@ -790,124 +883,13 @@ write_frame(bool fin,
     }
 }
 
-//------------------------------------------------------------------------------
-
-template<class NextLayer>
-template<class Buffers, class Handler>
-class stream<NextLayer>::write_op
-{
-    struct data : op
-    {
-        int step = 0;
-        stream<NextLayer>& ws;
-        consuming_buffers<Buffers> cb;
-        std::size_t remain;
-
-        data(Handler& handler, stream<NextLayer>& ws_,
-                Buffers const& bs)
-            : ws(ws_)
-            , cb(bs)
-            , remain(boost::asio::buffer_size(cb))
-        {
-        }
-    };
-
-    handler_ptr<data, Handler> d_;
-
-public:
-    write_op(write_op&&) = default;
-    write_op(write_op const&) = default;
-
-    template<class DeducedHandler, class... Args>
-    explicit
-    write_op(DeducedHandler&& h,
-            stream<NextLayer>& ws, Args&&... args)
-        : d_(std::forward<DeducedHandler>(h),
-            ws, std::forward<Args>(args)...)
-    {
-    }
-
-    void operator()(error_code ec);
-
-    friend
-    void* asio_handler_allocate(
-        std::size_t size, write_op* op)
-    {
-        using boost::asio::asio_handler_allocate;
-        return asio_handler_allocate(
-            size, std::addressof(op->d_.handler()));
-    }
-
-    friend
-    void asio_handler_deallocate(
-        void* p, std::size_t size, write_op* op)
-    {
-        using boost::asio::asio_handler_deallocate;
-        asio_handler_deallocate(
-            p, size, std::addressof(op->d_.handler()));
-    }
-
-    friend
-    bool asio_handler_is_continuation(write_op* op)
-    {
-        using boost::asio::asio_handler_is_continuation;
-        return op->d_->step > 2 ||
-            asio_handler_is_continuation(
-                std::addressof(op->d_.handler()));
-    }
-
-    template<class Function>
-    friend
-    void asio_handler_invoke(Function&& f, write_op* op)
-    {
-        using boost::asio::asio_handler_invoke;
-        asio_handler_invoke(
-            f, std::addressof(op->d_.handler()));
-    }
-};
-
-template<class NextLayer>
-template<class Buffers, class Handler>
-void
-stream<NextLayer>::
-write_op<Buffers, Handler>::
-operator()(error_code ec)
-{
-    auto& d = *d_;
-    switch(d.step)
-    {
-    case 2:
-        d.step = 3;
-        BOOST_FALLTHROUGH;
-    case 3:
-    case 0:
-    {
-        auto const n = d.remain;
-        d.remain -= n;
-        auto const fin = d.remain <= 0;
-        if(fin)
-            d.step = d.step ? 4 : 1;
-        else
-            d.step = d.step ? 3 : 2;
-        auto const pb = buffer_prefix(n, d.cb);
-        d.cb.consume(n);
-        return d.ws.async_write_frame(
-            fin, pb, std::move(*this));
-    }
-
-    case 1:
-    case 4:
-        break;
-    }
-    d_.invoke(ec);
-}
-
 template<class NextLayer>
 template<class ConstBufferSequence, class WriteHandler>
 async_return_type<
     WriteHandler, void(error_code)>
 stream<NextLayer>::
-async_write(ConstBufferSequence const& bs, WriteHandler&& handler)
+async_write_frame(bool fin,
+    ConstBufferSequence const& bs, WriteHandler&& handler)
 {
     static_assert(is_async_stream<next_layer_type>::value,
         "AsyncStream requirements not met");
@@ -916,13 +898,14 @@ async_write(ConstBufferSequence const& bs, WriteHandler&& handler)
             "ConstBufferSequence requirements not met");
     async_completion<WriteHandler,
         void(error_code)> init{handler};
-    write_op<ConstBufferSequence, handler_type<
-        WriteHandler, void(error_code)>>{
-            init.completion_handler, *this, bs}(
-                error_code{});
+    write_frame_op<ConstBufferSequence, handler_type<
+        WriteHandler, void(error_code)>>{init.completion_handler,
+            *this, fin, bs};
     return init.result.get();
 }
 
+//------------------------------------------------------------------------------
+
 template<class NextLayer>
 template<class ConstBufferSequence>
 void
@@ -954,6 +937,28 @@ write(ConstBufferSequence const& buffers, error_code& ec)
     write_frame(true, buffers, ec);
 }
 
+template<class NextLayer>
+template<class ConstBufferSequence, class WriteHandler>
+async_return_type<
+    WriteHandler, void(error_code)>
+stream<NextLayer>::
+async_write(
+    ConstBufferSequence const& bs, WriteHandler&& handler)
+{
+    static_assert(is_async_stream<next_layer_type>::value,
+        "AsyncStream requirements not met");
+    static_assert(beast::is_const_buffer_sequence<
+        ConstBufferSequence>::value,
+            "ConstBufferSequence requirements not met");
+    async_completion<WriteHandler,
+        void(error_code)> init{handler};
+    write_op<ConstBufferSequence, handler_type<
+        WriteHandler, void(error_code)>>{
+            init.completion_handler, *this, bs}(
+                error_code{});
+    return init.result.get();
+}
+
 } // websocket
 } // beast
 

include/beast/websocket/stream.hpp

@@ -47,17 +47,15 @@ using response_type = http::response<http::string_body>;
     that they are are all performed within the same implicit
     or explicit strand.
 
+    @par Thread Safety
+    @e Distinct @e objects: Safe.@n
+    @e Shared @e objects: Unsafe.
+
     @par Example
 
     To use the @ref stream template with an `ip::tcp::socket`,
     you would write:
 
-    @tparam NextLayer The type representing the next layer, to which
-    data will be read and written during operations. For synchronous
-    operations, the type must support the @b SyncStream concept.
-    For asynchronous operations, the type must support the
-    @b AsyncStream concept.
-
     @code
     websocket::stream<ip::tcp::socket> ws{io_service};
     @endcode
@@ -67,9 +65,11 @@ using response_type = http::response<http::string_body>;
     websocket::stream<ip::tcp::socket&> ws{sock};
     @endcode
 
-    @par Thread Safety
-    @e Distinct @e objects: Safe.@n
-    @e Shared @e objects: Unsafe.
+    @tparam NextLayer The type representing the next layer, to which
+    data will be read and written during operations. For synchronous
+    operations, the type must support the @b SyncStream concept.
+    For asynchronous operations, the type must support the
+    @b AsyncStream concept.
 
     @note A stream object must not be moved or destroyed while there
     are pending asynchronous operations associated with it.