Doc tidying

doc/qbk/release_notes.qbk

@@ -67,23 +67,10 @@
 
 [heading Boost 1.70]
 
-[/
-
-Exposition:
-Enlarged scope
-- `net` is a namespace alias for `boost::asio`
-  async_op_base, stable_async_op_base
-- New Networking refresher
-- New websocket-chat-multi example
-]
-
-[/-----------------------------------------------------------------------------]
-
 [tip
   The namespace alias `net` is used throughout for `boost::asio`.
 ]
 
-
 [/ includes up to version 209]
 
 

example/common/detect_ssl.hpp

@@ -211,9 +211,11 @@ detect_ssl(
     @param buffer The dynamic buffer to use. This type must meet the
     requirements of @b DynamicBuffer.
 
-    @param handler Invoked when the operation completes.
+    @param handler The completion handler to invoke when the operation
-    The handler may be moved or copied as needed.
+    completes. The implementation takes ownership of the handler by
-    The equivalent function signature of the handler must be:
+    performing a decay-copy. The equivalent function signature of
+    the handler must be:
+
     @code
     void handler(
         error_code const& error,    // Set to the error, if any
@@ -223,7 +225,7 @@ detect_ssl(
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
-    manner equivalent to using `boost::asio::io_context::post`.
+    manner equivalent to using `net::post`.
 */
 template<
     class AsyncReadStream,

example/echo-op/echo_op.cpp

@@ -69,8 +69,8 @@ async_echo (AsyncStream& stream, DynamicBuffer& buffer, CompletionToken&& token)
     extended least until the completion handler is invoked.
 
     @param token The handler to be called when the operation completes.
-    The implementation will take ownership of the handler by move
+    The implementation takes ownership of the handler by performing a decay-copy.
-    construction. The handler must be invocable with this signature:
+    The handler must be invocable with this signature:
     @code
     void handler(
         beast::error_code error      // Result of operation.

include/boost/beast/_experimental/http/icy_stream.hpp

@@ -208,16 +208,23 @@ public:
         buffers object may be copied as necessary, ownership of the underlying
         buffers is retained by the caller, which must guarantee that they remain
         valid until the handler is called.
-        
+
-        @param handler The handler to be called when the read operation completes.
+        @param handler The completion handler to invoke when the operation
-        Copies will be made of the handler as required. The equivalent function
+        completes. The implementation takes ownership of the handler by
-        signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code void handler(
           const boost::system::error_code& error, // Result of operation.
           std::size_t bytes_transferred           // Number of bytes read.
         ); @endcode
-        
+
-        @note The `read_some` operation may not read all of the requested number of
+        Regardless of whether the asynchronous operation completes
+        immediately or not, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed in a
+        manner equivalent to using `net::post`.
+
+        @note The `async_read_some` operation may not read all of the requested number of
         bytes. Consider using the function `net::async_read` if you need
         to ensure that the requested amount of data is read before the asynchronous
         operation completes.
@@ -283,13 +290,19 @@ public:
         retained by the caller, which must guarantee that they remain valid until
         the handler is called.
         
-        @param handler The handler to be called when the write operation completes.
+        @param handler The completion handler to invoke when the operation
-        Copies will be made of the handler as required. The equivalent function
+        completes. The implementation takes ownership of the handler by
-        signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code void handler(
           const boost::system::error_code& error, // Result of operation.
           std::size_t bytes_transferred           // Number of bytes written.
         ); @endcode
+        Regardless of whether the asynchronous operation completes
+        immediately or not, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed in a
+        manner equivalent to using `net::post`.
         
         @note The `async_write_some` operation may not transmit all of the data to
         the peer. Consider using the function `net::async_write` if you need

include/boost/beast/_experimental/test/stream.hpp

@@ -378,15 +378,23 @@ public:
         buffers is retained by the caller, which must guarantee that they remain
         valid until the handler is called.
 
-        @param handler The handler to be called when the read operation completes.
+        @param handler The completion handler to invoke when the operation
-        Copies will be made of the handler as required. The equivalent function
+        completes. The implementation takes ownership of the handler by
-        signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
-        @code void handler(
+        the handler must be:
-          const boost::system::error_code& error, // Result of operation.
-          std::size_t bytes_transferred           // Number of bytes read.
-        ); @endcode
 
-        @note The `read_some` operation may not read all of the requested number of
+        @code
+        void handler(
+            error_code const& ec,           // Result of operation.
+            std::size_t bytes_transferred   // Number of bytes read.
+        );
+        @endcode
+        Regardless of whether the asynchronous operation completes
+        immediately or not, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed in a
+        manner equivalent to using `net::post`.
+
+        @note The `async_read_some` operation may not read all of the requested number of
         bytes. Consider using the function `net::async_read` if you need
         to ensure that the requested amount of data is read before the asynchronous
         operation completes.
@@ -448,13 +456,21 @@ public:
         retained by the caller, which must guarantee that they remain valid until
         the handler is called.
 
-        @param handler The handler to be called when the write operation completes.
+        @param handler The completion handler to invoke when the operation
-        Copies will be made of the handler as required. The equivalent function
+        completes. The implementation takes ownership of the handler by
-        signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
-        @code void handler(
+        the handler must be:
-          const boost::system::error_code& error, // Result of operation.
+
-          std::size_t bytes_transferred           // Number of bytes written.
+        @code
-        ); @endcode
+        void handler(
+            error_code const& ec,           // Result of operation.
+          std::size_t bytes_transferred     // Number of bytes written.
+        );
+        @endcode
+        Regardless of whether the asynchronous operation completes
+        immediately or not, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed in a
+        manner equivalent to using `net::post`.
 
         @note The `async_write_some` operation may not transmit all of the data to
         the peer. Consider using the function `net::async_write` if you need

include/boost/beast/core/async_op_base.hpp

@@ -197,8 +197,9 @@ class async_op_base
 public:
     /** Constructor
 
-        @param handler The final completion handler. The type of this
+        @param handler The final completion handler.
-        object must meet the requirements of <em>CompletionHandler</em>.
+        The type of this object must meet the requirements of <em>CompletionHandler</em>.
+        The implementation takes ownership of the handler by performing a decay-copy.
 
         @param ex1 The executor associated with the implied I/O object
         target of the operation. The implementation shall maintain an
@@ -613,8 +614,9 @@ class stable_async_op_base
 public:
     /** Constructor
 
-        @param handler The final completion handler. The type of this
+        @param handler The final completion handler.
-        object must meet the requirements of <em>CompletionHandler</em>.
+        The type of this object must meet the requirements of <em>CompletionHandler</em>.
+        The implementation takes ownership of the handler by performing a decay-copy.
 
         @param ex1 The executor associated with the implied I/O object
         target of the operation. The implementation shall maintain an

include/boost/beast/core/basic_stream.hpp

@@ -883,9 +883,11 @@ public:
         @param ep The remote endpoint to which the underlying socket will be
         connected. Copies will be made of the endpoint object as required.
         
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code ec         // Result of operation
@@ -925,9 +927,11 @@ public:
         @param endpoints A sequence of endpoints. This this object must meet
         the requirements of <em>EndpointSequence</em>.
     
-        @param handler The handler to be called when the connect operation
+        @param handler The completion handler to invoke when the operation
-        completes. Ownership of the handler may be transferred. The function
+        completes. The implementation takes ownership of the handler by
-        signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             // Result of operation. if the sequence is empty, set to
@@ -940,10 +944,10 @@ public:
             typename Protocol::endpoint const& endpoint
         );
         @endcode
-        Regardless of whether the asynchronous operation completes immediately
+        Regardless of whether the asynchronous operation completes
-        or not, the handler will not be invoked from within this function.
+        immediately or not, the handler will not be invoked from within
-        Invocation of the handler will be performed in a manner equivalent
+        this function. Invocation of the handler will be performed in a
-        to using `net::post`.
+        manner equivalent to using `net::post`.
     */
     template<
         class EndpointSequence,
@@ -993,9 +997,11 @@ public:
         The function object should return true if the next endpoint should be tried,
         and false if it should be skipped.
 
-        @param handler The handler to be called when the connect operation
+        @param handler The completion handler to invoke when the operation
-        completes. Ownership of the handler may be transferred. The function
+        completes. The implementation takes ownership of the handler by
-        signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             // Result of operation. if the sequence is empty, set to
@@ -1008,10 +1014,10 @@ public:
             typename Protocol::endpoint const& endpoint
         );
         @endcode
-        Regardless of whether the asynchronous operation completes immediately
+        Regardless of whether the asynchronous operation completes
-        or not, the handler will not be invoked from within this function.
+        immediately or not, the handler will not be invoked from within
-        Invocation of the handler will be performed in a manner equivalent
+        this function. Invocation of the handler will be performed in a
-        to using `net::post`.
+        manner equivalent to using `net::post`.
 
         @par Example
         The following connect condition function object can be used to output
@@ -1069,9 +1075,11 @@ public:
     
         @param end An iterator pointing to the end of a sequence of endpoints.
 
-        @param handler The handler to be called when the connect operation
+        @param handler The completion handler to invoke when the operation
-        completes. Ownership of the handler may be transferred. The function
+        completes. The implementation takes ownership of the handler by
-        signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             // Result of operation. if the sequence is empty, set to
@@ -1084,10 +1092,10 @@ public:
             Iterator iterator
         );
         @endcode
-        Regardless of whether the asynchronous operation completes immediately
+        Regardless of whether the asynchronous operation completes
-        or not, the handler will not be invoked from within this function.
+        immediately or not, the handler will not be invoked from within
-        Invocation of the handler will be performed in a manner equivalent
+        this function. Invocation of the handler will be performed in a
-        to using `net::post`.
+        manner equivalent to using `net::post`.
     */
     template<
         class Iterator,
@@ -1122,9 +1130,12 @@ public:
             error_code const& ec,
             Iterator next);
         @endcode
-        @param handler The handler to be called when the connect operation
+
-        completes. Ownership of the handler may be transferred. The function
+        @param handler The completion handler to invoke when the operation
-        signature of the handler must be:
+        completes. The implementation takes ownership of the handler by
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             // Result of operation. if the sequence is empty, set to
@@ -1137,10 +1148,10 @@ public:
             Iterator iterator
         );
         @endcode
-        Regardless of whether the asynchronous operation completes immediately
+        Regardless of whether the asynchronous operation completes
-        or not, the handler will not be invoked from within this function.
+        immediately or not, the handler will not be invoked from within
-        Invocation of the handler will be performed in a manner equivalent
+        this function. Invocation of the handler will be performed in a
-        to using `net::post`.
+        manner equivalent to using `net::post`.
     */
     template<
         class Iterator,
@@ -1244,19 +1255,21 @@ public:
         underlying memory blocks is retained by the caller, which must guarantee
         that they remain valid until the handler is called.
         
-        @param handler The handler to be called when the operation completes.
+        @param handler The completion handler to invoke when the operation
-        The implementation will take ownership of the handler by move construction.
+        completes. The implementation takes ownership of the handler by
-        The handler must be invocable with this signature:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code error,               // Result of operation.
             std::size_t bytes_transferred   // Number of bytes read.
         );
         @endcode
-        Regardless of whether the asynchronous operation completes immediately or
+        Regardless of whether the asynchronous operation completes
-        not, the handler will not be invoked from within this function. Invocation
+        immediately or not, the handler will not be invoked from within
-        of the handler will be performed in a manner equivalent to using
+        this function. Invocation of the handler will be performed in a
-        `net::post`.
+        manner equivalent to using `net::post`.
 
         @note The `async_read_some` operation may not receive all of the requested
         number of bytes. Consider using the function `net::async_read` if you need
@@ -1361,19 +1374,21 @@ public:
         underlying memory blocks is retained by the caller, which must guarantee
         that they remain valid until the handler is called.
         
-        @param handler The handler to be called when the operation completes.
+        @param handler The completion handler to invoke when the operation
-        The implementation will take ownership of the handler by move construction.
+        completes. The implementation takes ownership of the handler by
-        The handler must be invocable with this signature:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code error,               // Result of operation.
             std::size_t bytes_transferred   // Number of bytes written.
         );
         @endcode
-        Regardless of whether the asynchronous operation completes immediately or
+        Regardless of whether the asynchronous operation completes
-        not, the handler will not be invoked from within this function. Invocation
+        immediately or not, the handler will not be invoked from within
-        of the handler will be performed in a manner equivalent to using
+        this function. Invocation of the handler will be performed in a
-        `net::post`.
+        manner equivalent to using `net::post`.
 
         @note The `async_write_some` operation may not transmit all of the requested
         number of bytes. Consider using the function `net::async_write` if you need

include/boost/beast/core/bind_handler.hpp

@@ -48,6 +48,7 @@ namespace beast {
     @endcode
 
     @param handler The handler to wrap.
+    The implementation takes ownership of the handler by performing a decay-copy.
 
     @param args A list of arguments to bind to the handler.
     The arguments are forwarded into the returned object. These
@@ -100,6 +101,7 @@ bind_handler(Handler&& handler, Args&&... args)
     @endcode
 
     @param handler The handler to wrap.
+    The implementation takes ownership of the handler by performing a decay-copy.
 
     @param args A list of arguments to bind to the handler.
     The arguments are forwarded into the returned object.

include/boost/beast/core/buffered_read_stream.hpp

@@ -247,17 +247,21 @@ public:
         is retained by the caller, which must guarantee that they
         remain valid until the handler is called.
 
-        @param handler Invoked when the operation completes.
+        @param handler The completion handler to invoke when the operation
-        The handler may be moved or copied as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
-        @code void handler(
+        the handler must be:
+
+        @code
+        void handler(
             error_code const& error,      // result of operation
             std::size_t bytes_transferred // number of bytes transferred
-        ); @endcode
+        );
+        @endcode
         Regardless of whether the asynchronous operation completes
         immediately or not, the handler will not be invoked from within
         this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::io_context::post`.
+        manner equivalent to using `net::post`.
     */
     template<class MutableBufferSequence, class ReadHandler>
     BOOST_ASIO_INITFN_RESULT_TYPE(
@@ -319,17 +323,21 @@ public:
         retained by the caller, which must guarantee that they
         remain valid until the handler is called.
 
-        @param handler Invoked when the operation completes.
+        @param handler The completion handler to invoke when the operation
-        The handler may be moved or copied as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
-        @code void handler(
+        the handler must be:
+
+        @code
+        void handler(
             error_code const& error,      // result of operation
             std::size_t bytes_transferred // number of bytes transferred
-        ); @endcode
+        );
+        @endcode
         Regardless of whether the asynchronous operation completes
         immediately or not, the handler will not be invoked from within
         this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::io_context::post`.
+        manner equivalent to using `net::post`.
     */
     template<class ConstBufferSequence, class WriteHandler>
     BOOST_ASIO_INITFN_RESULT_TYPE(

include/boost/beast/core/detail/bind_continuation.hpp

@@ -32,6 +32,7 @@ namespace detail {
     flow of control.
 
     @param handler The handler to wrap.
+    The implementation takes ownership of the handler by performing a decay-copy.
 
     @see
 
@@ -67,6 +68,7 @@ bind_continuation(CompletionHandler&& handler)
     @param ex The executor to use
 
     @param handler The handler to wrap
+    The implementation takes ownership of the handler by performing a decay-copy.
 
     @see
 

include/boost/beast/core/detail/read.hpp

@@ -194,9 +194,11 @@ read(
     in this case the optionally modifiable error passed to the completion
     condition will be delivered to the completion handler.
 
-    @param handler The handler to be called when the read operation completes.
+    @param handler The completion handler to invoke when the operation
-    The handler will be moved as needed. The handler must be invocable with
+    completes. The implementation takes ownership of the handler by
-    this function signature:
+    performing a decay-copy. The equivalent function signature of
+    the handler must be:
+
     @code
     void
     handler(
@@ -209,10 +211,10 @@ read(
                                             // prior to the error.
     );
     @endcode
-    Regardless of whether the asynchronous operation completes immediately or
+    Regardless of whether the asynchronous operation completes
-    not, the handler will not be invoked from within this function. Invocation
+    immediately or not, the handler will not be invoked from within
-    of the handler will be performed in a manner equivalent to using
+    this function. Invocation of the handler will be performed in a
-    `net::io_context::post()`.
+    manner equivalent to using `net::post`.
 */
 template<
     class AsyncReadStream,

include/boost/beast/core/flat_stream.hpp

@@ -231,13 +231,21 @@ public:
         buffers is retained by the caller, which must guarantee that they remain
         valid until the handler is called.
         
-        @param handler The handler to be called when the read operation completes.
+        @param handler The completion handler to invoke when the operation
-        Copies will be made of the handler as required. The equivalent function
+        completes. The implementation takes ownership of the handler by
-        signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
-        @code void handler(
+        the handler must be:
-          const boost::system::error_code& error, // Result of operation.
+
-          std::size_t bytes_transferred           // Number of bytes read.
+        @code
-        ); @endcode
+        void handler(
+            error_code const& error,        // Result of operation.
+          std::size_t bytes_transferred     // Number of bytes read.
+        );
+        @endcode
+        Regardless of whether the asynchronous operation completes
+        immediately or not, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed in a
+        manner equivalent to using `net::post`.
         
         @note The `read_some` operation may not read all of the requested number of
         bytes. Consider using the function `net::async_read` if you need
@@ -305,13 +313,21 @@ public:
         retained by the caller, which must guarantee that they remain valid until
         the handler is called.
         
-        @param handler The handler to be called when the write operation completes.
+        @param handler The completion handler to invoke when the operation
-        Copies will be made of the handler as required. The equivalent function
+        completes. The implementation takes ownership of the handler by
-        signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
-        @code void handler(
+        the handler must be:
-          const boost::system::error_code& error, // Result of operation.
+
-          std::size_t bytes_transferred           // Number of bytes written.
+        @code
-        ); @endcode
+        void handler(
+          error_code const& ec,             // Result of operation.
+          std::size_t bytes_transferred     // Number of bytes written.
+        );
+        @endcode
+        Regardless of whether the asynchronous operation completes
+        immediately or not, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed in a
+        manner equivalent to using `net::post`.
         
         @note The `async_write_some` operation may not transmit all of the data to
         the peer. Consider using the function `net::async_write` if you need

include/boost/beast/core/handler_ptr.hpp

@@ -106,8 +106,8 @@ public:
         @par Exception Safety
         Strong guarantee.
 
-        @param handler The handler to associate with the owned
+        @param handler The handler to associate with the owned object.
-        object. The argument will be moved if it is an xvalue.
+        The implementation takes ownership of the handler by performing a decay-copy.
 
         @param args Optional arguments forwarded to
         the owned object's constructor.

include/boost/beast/core/saved_handler.hpp

@@ -69,6 +69,7 @@ public:
         Requires `this->has_value() == false`.
 
         @param handler The completion handler to store.
+        The implementation takes ownership of the handler by performing a decay-copy.
 
         @param alloc The allocator to use.
     */
@@ -83,6 +84,7 @@ public:
         allocator to obtian storage.
 
         @param handler The completion handler to store.
+        The implementation takes ownership of the handler by performing a decay-copy.
     */
     template<class Handler>
     void

include/boost/beast/http/read.hpp

@@ -181,9 +181,11 @@ read_some(
     @param parser The parser to use. The object must remain valid at least until
     the handler is called; ownership is not transferred.
 
-    @param handler Invoked when the operation completes. The handler will
+    @param handler The completion handler to invoke when the operation
-    be moved as needed. The handler must be invocable with the following
+    completes. The implementation takes ownership of the handler by
-    signature:
+    performing a decay-copy. The equivalent function signature of
+    the handler must be:
+
     @code
     void handler(
         error_code const& error,        // result of operation
@@ -193,7 +195,7 @@ read_some(
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
-    manner equivalent to using `net::io_context::post`.
+    manner equivalent to using `net::post`.
 
     @note The completion handler will receive as a parameter the total number
     of bytes transferred from the stream. This may be zero for the case where
@@ -372,9 +374,11 @@ read_header(
     @param parser The parser to use. The object must remain valid at least until
     the handler is called; ownership is not transferred.
 
-    @param handler Invoked when the operation completes. The handler will
+    @param handler The completion handler to invoke when the operation
-    be moved as needed. The handler must be invocable with the following
+    completes. The implementation takes ownership of the handler by
-    signature:
+    performing a decay-copy. The equivalent function signature of
+    the handler must be:
+
     @code
     void handler(
         error_code const& error,        // result of operation
@@ -384,7 +388,7 @@ read_header(
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
-    manner equivalent to using `net::io_context::post`.
+    manner equivalent to using `net::post`.
 
     @note The completion handler will receive as a parameter the total number
     of bytes transferred from the stream. This may be zero for the case where
@@ -565,9 +569,11 @@ read(
     @param parser The parser to use. The object must remain valid at least until
     the handler is called; ownership is not transferred.
 
-    @param handler Invoked when the operation completes. The handler will
+    @param handler The completion handler to invoke when the operation
-    be moved as needed. The handler must be invocable with the following
+    completes. The implementation takes ownership of the handler by
-    signature:
+    performing a decay-copy. The equivalent function signature of
+    the handler must be:
+
     @code
     void handler(
         error_code const& error,        // result of operation
@@ -577,7 +583,7 @@ read(
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
-    manner equivalent to using `net::io_context::post`.
+    manner equivalent to using `net::post`.
 
     @note The completion handler will receive as a parameter the total number
     of bytes transferred from the stream. This may be zero for the case where
@@ -767,9 +773,11 @@ read(
     <em>MoveConstructible</em> requirements. The object must remain valid
     at least until the handler is called; ownership is not transferred.
 
-    @param handler Invoked when the operation completes. The handler will
+    @param handler The completion handler to invoke when the operation
-    be moved as needed. The handler must be invocable with the following
+    completes. The implementation takes ownership of the handler by
-    signature:
+    performing a decay-copy. The equivalent function signature of
+    the handler must be:
+
     @code
     void handler(
         error_code const& error,        // result of operation
@@ -779,7 +787,7 @@ read(
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
-    manner equivalent to using `net::io_context::post`.
+    manner equivalent to using `net::post`.
 
     @note The completion handler will receive as a parameter the total number
     of bytes transferred from the stream. This may be zero for the case where

include/boost/beast/http/write.hpp

@@ -149,17 +149,21 @@ write_some(
     The object must remain valid at least until the
     handler is called; ownership is not transferred.
 
-    @param handler Invoked when the operation completes.
+    @param handler The completion handler to invoke when the operation
-    The handler may be moved or copied as needed.
+    completes. The implementation takes ownership of the handler by
-    The equivalent function signature of the handler must be:
+    performing a decay-copy. The equivalent function signature of
-    @code void handler(
+    the handler must be:
+
+    @code
+    void handler(
         error_code const& error,        // result of operation
         std::size_t bytes_transferred   // the number of bytes written to the stream
-    ); @endcode
+    );
+    @endcode
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
-    manner equivalent to using `net::io_context::post`.
+    manner equivalent to using `net::post`.
 
     @see @ref serializer
 */
@@ -270,17 +274,21 @@ write_header(
     The object must remain valid at least until the
     handler is called; ownership is not transferred.
 
-    @param handler Invoked when the operation completes.
+    @param handler The completion handler to invoke when the operation
-    The handler may be moved or copied as needed.
+    completes. The implementation takes ownership of the handler by
-    The equivalent function signature of the handler must be:
+    performing a decay-copy. The equivalent function signature of
-    @code void handler(
+    the handler must be:
+
+    @code
+    void handler(
         error_code const& error,        // result of operation
         std::size_t bytes_transferred   // the number of bytes written to the stream
-    ); @endcode
+    );
+    @endcode
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
-    manner equivalent to using `net::io_context::post`.
+    manner equivalent to using `net::post`.
 
     @note The implementation will call @ref serializer::split with
     the value `true` on the serializer passed in.
@@ -388,17 +396,21 @@ write(
     The object must remain valid at least until the
     handler is called; ownership is not transferred.
 
-    @param handler Invoked when the operation completes.
+    @param handler The completion handler to invoke when the operation
-    The handler may be moved or copied as needed.
+    completes. The implementation takes ownership of the handler by
-    The equivalent function signature of the handler must be:
+    performing a decay-copy. The equivalent function signature of
-    @code void handler(
+    the handler must be:
+
+    @code
+    void handler(
         error_code const& error,        // result of operation
         std::size_t bytes_transferred   // the number of bytes written to the stream
-    ); @endcode
+    );
+    @endcode
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
-    manner equivalent to using `net::io_context::post`.
+    manner equivalent to using `net::post`.
 
     @see @ref serializer
 */
@@ -607,17 +619,21 @@ write(
     The object must remain valid at least until the
     handler is called; ownership is not transferred.
 
-    @param handler Invoked when the operation completes.
+    @param handler The completion handler to invoke when the operation
-    The handler may be moved or copied as needed.
+    completes. The implementation takes ownership of the handler by
-    The equivalent function signature of the handler must be:
+    performing a decay-copy. The equivalent function signature of
-    @code void handler(
+    the handler must be:
+
+    @code
+    void handler(
         error_code const& error,        // result of operation
         std::size_t bytes_transferred   // the number of bytes written to the stream
-    ); @endcode
+    );
+    @endcode
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
-    manner equivalent to using `net::io_context::post`.
+    manner equivalent to using `net::post`.
 
     @see @ref message
 */
@@ -665,17 +681,21 @@ async_write(
     The object must remain valid at least until the
     handler is called; ownership is not transferred.
 
-    @param handler Invoked when the operation completes.
+    @param handler The completion handler to invoke when the operation
-    The handler may be moved or copied as needed.
+    completes. The implementation takes ownership of the handler by
-    The equivalent function signature of the handler must be:
+    performing a decay-copy. The equivalent function signature of
-    @code void handler(
+    the handler must be:
+
+    @code
+    void handler(
         error_code const& error,        // result of operation
         std::size_t bytes_transferred   // the number of bytes written to the stream
-    ); @endcode
+    );
+    @endcode
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
-    manner equivalent to using `net::io_context::post`.
+    manner equivalent to using `net::post`.
 
     @see @ref message
 */

include/boost/beast/websocket/ssl.hpp

@@ -55,16 +55,20 @@ teardown(
 
     @param stream The stream to tear down.
 
-    @param handler Invoked when the operation completes.
+    @param handler The completion handler to invoke when the operation
-    The handler may be moved or copied as needed.
+    completes. The implementation takes ownership of the handler by
-    The equivalent function signature of the handler must be:
+    performing a decay-copy. The equivalent function signature of
-    @code void handler(
+    the handler must be:
+
+    @code
+    void handler(
         error_code const& error // result of operation
-    ); @endcode
+    );
+    @endcode
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
-    manner equivalent to using net::io_context::post().
+    manner equivalent to using `net::post`.
 
 */
 template<class AsyncStream, class TeardownHandler>

include/boost/beast/websocket/stream.hpp

@@ -849,9 +849,11 @@ public:
         The implementation will not access the string data after the
         initiating function returns.
 
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code const& ec    // Result of operation
@@ -861,7 +863,7 @@ public:
         immediately or not, the handler will not be invoked from within
         this function. Invocation of the handler will be performed in a
         manner equivalent to using `net::post`.
-
+    
         @par Example
         @code
         ws.async_handshake("localhost", "/",
@@ -926,9 +928,11 @@ public:
         The implementation will not access the string data after the
         initiating function returns.
 
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code const& ec    // Result of operation
@@ -1262,9 +1266,11 @@ public:
         pass the request to the appropriate overload of @ref accept or
         @ref async_accept
 
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code const& ec    // Result of operation
@@ -1323,9 +1329,11 @@ public:
         then to received WebSocket frames. The implementation will
         copy the caller provided data before the function returns.
 
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code const& ec    // Result of operation
@@ -1384,9 +1392,11 @@ public:
         Ownership is not transferred, the implementation will not access
         this object from other threads.
 
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code const& ec    // Result of operation
@@ -1516,9 +1526,11 @@ public:
         sent with the close code and optional reason string. Otherwise,
         the close frame is sent with no payload.
 
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code const& ec     // Result of operation
@@ -1614,9 +1626,11 @@ public:
         The implementation will not access the contents of this object after
         the initiating function returns.
 
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code const& ec     // Result of operation
@@ -1715,9 +1729,11 @@ public:
         The implementation will not access the contents of this object after
         the initiating function returns.
 
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code const& ec     // Result of operation
@@ -1868,9 +1884,11 @@ public:
 
         @param buffer A dynamic buffer to append message data to.
 
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code const& ec,       // Result of operation
@@ -2041,9 +2059,11 @@ public:
         will append into the buffer. If this value is zero, then a reasonable
         size will be chosen automatically.
 
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code const& ec,       // Result of operation
@@ -2210,9 +2230,11 @@ public:
         pointed to by the buffer sequence remain valid until the
         completion handler is called.
 
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code const& ec,       // Result of operation
@@ -2325,9 +2347,11 @@ public:
         the memory locations pointed to by buffers remains valid
         until the completion handler is called.
 
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code const& ec,           // Result of operation
@@ -2444,9 +2468,11 @@ public:
         the memory locations pointed to by buffers remains valid
         until the completion handler is called.
 
-        @param handler Invoked when the operation completes. Ownership
+        @param handler The completion handler to invoke when the operation
-        of the handler will be transferred by move-construction as needed.
+        completes. The implementation takes ownership of the handler by
-        The equivalent function signature of the handler must be:
+        performing a decay-copy. The equivalent function signature of
+        the handler must be:
+
         @code
         void handler(
             error_code const& ec,           // Result of operation

include/boost/beast/websocket/teardown.hpp

@@ -69,17 +69,20 @@ teardown(
 
     @param socket The socket to tear down.
 
-    @param handler Invoked when the operation completes.
+    @param handler The completion handler to invoke when the operation
-    The handler may be moved or copied as needed.
+    completes. The implementation takes ownership of the handler by
-    The equivalent function signature of the handler must be:
+    performing a decay-copy. The equivalent function signature of
-    @code void handler(
+    the handler must be:
+
+    @code
+    void handler(
         error_code const& error // result of operation
     );
     @endcode
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
-    manner equivalent to using net::io_context::post().
+    manner equivalent to using `net::post`.
 
 */
 template<
@@ -147,17 +150,20 @@ teardown(
 
     @param socket The socket to tear down.
 
-    @param handler Invoked when the operation completes.
+    @param handler The completion handler to invoke when the operation
-    The handler may be moved or copied as needed.
+    completes. The implementation takes ownership of the handler by
-    The equivalent function signature of the handler must be:
+    performing a decay-copy. The equivalent function signature of
-    @code void handler(
+    the handler must be:
+
+    @code
+    void handler(
         error_code const& error // result of operation
     );
     @endcode
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
-    manner equivalent to using net::io_context::post().
+    manner equivalent to using `net::post`.
 
 */
 template<