Various documentation fixes and improvements.

doc/reference.qbk

@@ -6079,7 +6079,7 @@ Used to generically specialise associators for a type.
 [indexterm1 boost_asio.indexterm.async_completion..async_completion]
 
 
-Helper template to deduce the handler type from a CompletionToken, capture a local copy of the handler, and then create an [link boost_asio.reference.async_result `async_result`] for the handler. 
+(Legacy.) Helper template to deduce the handler type from a CompletionToken, capture a local copy of the handler, and then create an [link boost_asio.reference.async_result `async_result`] for the handler. 
 
 
   template<
@@ -6248,7 +6248,9 @@ This template may be specialised for user-defined completion token types. The pr
       
 For backwards compatibility, the primary template implements member types and functions that are associated with legacy forms of the [link boost_asio.reference.async_result `async_result`] trait. These are annotated as "Legacy" in the documentation below. User specialisations of this trait do not need to implement these in order to satisfy the [link boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers async_result requirements].
 
-In general, implementers of asynchronous operations should use the async\_initiate function rather than using the [link boost_asio.reference.async_result `async_result`] trait directly. 
+In general, implementers of asynchronous operations should use the async\_initiate function rather than using the [link boost_asio.reference.async_result `async_result`] trait directly.
+
+For a more detailed discussion of the role of [link boost_asio.reference.async_result `async_result`] and async\_initiate, see the overview documentation for [link boost_asio.overview.model.completion_tokens completion token]. 
 
 
 [heading Requirements]
@@ -7114,6 +7116,8 @@ If the completion handler does not have a customised associated immediate execut
 
 [indexterm1 boost_asio.indexterm.async_initiate..async_initiate]
 
+Helper function for implementing an asynchronous operation's initiating function. 
+
 
   template<
       typename CompletionToken,
@@ -7126,6 +7130,34 @@ If the completion handler does not have a customised associated immediate execut
       Args &&... args);
 
 
+The async\_initiate function wraps the [link boost_asio.reference.async_result `async_result`] trait. It automatically performs the necessary decay and forward of the completion token, and also enables backwards compatibility with legacy completion token implementations.
+
+
+[heading Parameters]
+    
+
+[variablelist
+  
+[[initiation][A function object that will be called to launch the asynchronous operation. It receives the concrete completion handler as its first argument, followed by any additional arguments passed to async\_initiate.]]
+
+[[token][The [link boost_asio.overview.model.completion_tokens completion token] provided by the user. This will be transformed into a concrete completion handler by the [link boost_asio.reference.async_result `async_result`] trait.]]
+
+[[args][Additional arguments to be forwarded to the initiation function object.]]
+
+]
+
+
+[heading Return Value]
+      
+The return value is determined by the [link boost_asio.reference.async_result `async_result`] specialisation for the completion token type. For callback-based tokens, returns `void`. For other tokens such as use\_future or use\_awaitable, returns the corresponding future or awaitable type.
+
+
+[heading Remarks]
+      
+Asynchronous operation implementations should use this function rather than directly using the [link boost_asio.reference.async_result `async_result`] trait, or the legacy [link boost_asio.reference.async_completion `async_completion`] helper template.
+
+For a more detailed discussion of the role of [link boost_asio.reference.async_result `async_result`] and async\_initiate, see the overview documentation for [link boost_asio.overview.model.completion_tokens completion token]. 
+
 [heading Requirements]
 
 ['Header: ][^boost/asio/async_result.hpp]
@@ -10426,7 +10458,9 @@ This template may be specialised for user-defined completion token types. The pr
       
 For backwards compatibility, the primary template implements member types and functions that are associated with legacy forms of the [link boost_asio.reference.async_result `async_result`] trait. These are annotated as "Legacy" in the documentation below. User specialisations of this trait do not need to implement these in order to satisfy the [link boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers async_result requirements].
 
-In general, implementers of asynchronous operations should use the async\_initiate function rather than using the [link boost_asio.reference.async_result `async_result`] trait directly. 
+In general, implementers of asynchronous operations should use the async\_initiate function rather than using the [link boost_asio.reference.async_result `async_result`] trait directly.
+
+For a more detailed discussion of the role of [link boost_asio.reference.async_result `async_result`] and async\_initiate, see the overview documentation for [link boost_asio.overview.model.completion_tokens completion token]. 
 
 [heading Requirements]
 
@@ -85736,6 +85770,27 @@ The function call operator of `Init:`
 If the function object throws an exception, that exception is allowed to propagate to the target executor. The behaviour in this case is dependent on the executor. For example, [link boost_asio.reference.io_context `io_context`] will allow the exception to propagate to the caller that runs the `io_context`, whereas [link boost_asio.reference.thread_pool `thread_pool`] will call `std::terminate`.
 
 
+[heading Example]
+  
+This `defer` overload may be used to submit long running work to a thread pool and, once complete, continue execution on an associated completion executor, such as a coroutine's associated executor: 
+
+  boost::asio::awaitable<void> my_coroutine()
+  {
+     // ...
+
+     co_await boost::asio::defer(
+         []{
+           perform_expensive_computation();
+         },
+         my_thread_pool);
+
+     // handle result on the coroutine's associated executor
+  } 
+
+
+
+
+
 [heading Completion Signature]
   
 
@@ -85882,6 +85937,27 @@ The function call operator of `Init:`
 If the function object throws an exception, that exception is allowed to propagate to the target executor. The behaviour in this case is dependent on the executor. For example, [link boost_asio.reference.io_context `io_context`] will allow the exception to propagate to the caller that runs the `io_context`, whereas [link boost_asio.reference.thread_pool `thread_pool`] will call `std::terminate`.
 
 
+[heading Example]
+  
+This `defer` overload may be used to submit long running work to a thread pool and, once complete, continue execution on an associated completion executor, such as a coroutine's associated executor: 
+
+  boost::asio::awaitable<void> my_coroutine()
+  {
+     // ...
+
+     int result = co_await boost::asio::defer(
+         []{
+           return perform_expensive_computation();
+         },
+         my_thread_pool);
+
+     // handle result on the coroutine's associated executor
+  } 
+
+
+
+
+
 [heading Completion Signature]
   
 
@@ -114871,7 +114947,7 @@ Adapts an executor to add inline invocation of the submitted function.
   
 ]
 
-The @inline\_or\_executor class template adapts an existing executor such that:
+The `inline_or_executor` class template adapts an existing executor such that:
 
 
 * posted function objects (or when the `blocking` property is set to `blocking.never`) are submitted to the wrapped executor; and
@@ -148239,6 +148315,27 @@ The function call operator of `Init:`
 If the function object throws an exception, that exception is allowed to propagate to the target executor. The behaviour in this case is dependent on the executor. For example, [link boost_asio.reference.io_context `io_context`] will allow the exception to propagate to the caller that runs the `io_context`, whereas [link boost_asio.reference.thread_pool `thread_pool`] will call `std::terminate`.
 
 
+[heading Example]
+  
+This `post` overload may be used to submit long running work to a thread pool and, once complete, continue execution on an associated completion executor, such as a coroutine's associated executor: 
+
+  boost::asio::awaitable<void> my_coroutine()
+  {
+     // ...
+
+     co_await boost::asio::post(
+         []{
+           perform_expensive_computation();
+         },
+         my_thread_pool);
+
+     // handle result on the coroutine's associated executor
+  } 
+
+
+
+
+
 [heading Completion Signature]
   
 
@@ -148385,6 +148482,27 @@ The function call operator of `Init:`
 If the function object throws an exception, that exception is allowed to propagate to the target executor. The behaviour in this case is dependent on the executor. For example, [link boost_asio.reference.io_context `io_context`] will allow the exception to propagate to the caller that runs the `io_context`, whereas [link boost_asio.reference.thread_pool `thread_pool`] will call `std::terminate`.
 
 
+[heading Example]
+  
+This `post` overload may be used to submit long running work to a thread pool and, once complete, continue execution on an associated completion executor, such as a coroutine's associated executor: 
+
+  boost::asio::awaitable<void> my_coroutine()
+  {
+     // ...
+
+     int result = co_await boost::asio::post(
+         []{
+           return perform_expensive_computation();
+         },
+         my_thread_pool);
+
+     // handle result on the coroutine's associated executor
+  } 
+
+
+
+
+
 [heading Completion Signature]
   
 

include/boost/asio/async_result.hpp

@@ -379,6 +379,9 @@ private:
  *
  * In general, implementers of asynchronous operations should use the
  * async_initiate function rather than using the async_result trait directly.
+ *
+ * For a more detailed discussion of the role of async_result and
+ * async_initiate, see the overview documentation for @ref completion_token.
  */
 template <typename CompletionToken,
     BOOST_ASIO_COMPLETION_SIGNATURE... Signatures>
@@ -452,8 +455,8 @@ class async_result<void, Signatures...>
 
 #endif // defined(GENERATING_DOCUMENTATION)
 
-/// Helper template to deduce the handler type from a CompletionToken, capture
-/// a local copy of the handler, and then create an async_result for the
+/// (Legacy.) Helper template to deduce the handler type from a CompletionToken,
+/// capture a local copy of the handler, and then create an async_result for the
 /// handler.
 template <typename CompletionToken,
     BOOST_ASIO_COMPLETION_SIGNATURE... Signatures>
@@ -621,6 +624,36 @@ struct async_result_has_initiate_memfn
 
 #if defined(GENERATING_DOCUMENTATION)
 
+/// Helper function for implementing an asynchronous operation's initiating
+/// function.
+/**
+ * The async_initiate function wraps the async_result trait. It automatically
+ * performs the necessary decay and forward of the completion token, and also
+ * enables backwards compatibility with legacy completion token implementations.
+ *
+ * @param initiation A function object that will be called to launch the
+ * asynchronous operation. It receives the concrete completion handler as its
+ * first argument, followed by any additional arguments passed to
+ * async_initiate.
+ *
+ * @param token The @ref completion_token provided by the user. This will be
+ * transformed into a concrete completion handler by the async_result trait.
+ *
+ * @param args Additional arguments to be forwarded to the initiation function
+ * object.
+ *
+ * @returns The return value is determined by the async_result specialisation
+ * for the completion token type. For callback-based tokens, returns @c void.
+ * For other tokens such as use_future or use_awaitable, returns the
+ * corresponding future or awaitable type.
+ *
+ * @note Asynchronous operation implementations should use this function rather
+ * than directly using the async_result trait, or the legacy async_completion
+ * helper template.
+ *
+ * For a more detailed discussion of the role of async_result and
+ * async_initiate, see the overview documentation for @ref completion_token.
+ */
 template <typename CompletionToken,
     completion_signature... Signatures,
     typename Initiation, typename... Args>

include/boost/asio/defer.hpp

@@ -302,6 +302,23 @@ inline auto defer(ExecutionContext& ctx,
  * exception to propagate to the caller that runs the @c io_context, whereas
  * boost::asio::thread_pool will call @c std::terminate.
  *
+ * @par Example
+ * This @c defer overload may be used to submit long running work to a thread
+ * pool and, once complete, continue execution on an associated completion
+ * executor, such as a coroutine's associated executor:
+ * @code boost::asio::awaitable<void> my_coroutine()
+ * {
+ *    // ...
+ *
+ *    co_await boost::asio::defer(
+ *        []{
+ *          perform_expensive_computation();
+ *        },
+ *        my_thread_pool);
+ *
+ *    // handle result on the coroutine's associated executor
+ * } @endcode
+ *
  * @par Completion Signature
  * @code void() @endcode
  */
@@ -415,6 +432,23 @@ inline auto defer(Function&& function, const Executor& ex,
  * exception to propagate to the caller that runs the @c io_context, whereas
  * boost::asio::thread_pool will call @c std::terminate.
  *
+ * @par Example
+ * This @c defer overload may be used to submit long running work to a thread
+ * pool and, once complete, continue execution on an associated completion
+ * executor, such as a coroutine's associated executor:
+ * @code boost::asio::awaitable<void> my_coroutine()
+ * {
+ *    // ...
+ *
+ *    int result = co_await boost::asio::defer(
+ *        []{
+ *          return perform_expensive_computation();
+ *        },
+ *        my_thread_pool);
+ *
+ *    // handle result on the coroutine's associated executor
+ * } @endcode
+ *
  * @par Completion Signature
  * @code void(decay_t<result_of_t<decay_t<Function>()>>) @endcode
  */

include/boost/asio/inline_or_executor.hpp

@@ -31,10 +31,11 @@ namespace asio {
 
 /// Adapts an executor to add inline invocation of the submitted function.
 /**
- * The @inline_or_executor class template adapts an existing executor such that:
+ * The @c inline_or_executor class template adapts an existing executor such
+ * that:
  *
  * @li posted function objects (or when the @c blocking property is set to
- *     @c blocking.never) are submitted to the wrapped executor; and
+ * @c blocking.never) are submitted to the wrapped executor; and
  *
  * @li dispatched function objects (or when @c blocking is @c blocking.always or
  * @c blocking.possibly) are executed inline.

include/boost/asio/post.hpp

@@ -295,6 +295,23 @@ inline auto post(ExecutionContext& ctx,
  * exception to propagate to the caller that runs the @c io_context, whereas
  * boost::asio::thread_pool will call @c std::terminate.
  *
+ * @par Example
+ * This @c post overload may be used to submit long running work to a thread
+ * pool and, once complete, continue execution on an associated completion
+ * executor, such as a coroutine's associated executor:
+ * @code boost::asio::awaitable<void> my_coroutine()
+ * {
+ *    // ...
+ *
+ *    co_await boost::asio::post(
+ *        []{
+ *          perform_expensive_computation();
+ *        },
+ *        my_thread_pool);
+ *
+ *    // handle result on the coroutine's associated executor
+ * } @endcode
+ *
  * @par Completion Signature
  * @code void() @endcode
  */
@@ -406,6 +423,23 @@ inline auto post(Function&& function, const Executor& ex,
  * exception to propagate to the caller that runs the @c io_context, whereas
  * boost::asio::thread_pool will call @c std::terminate.
  *
+ * @par Example
+ * This @c post overload may be used to submit long running work to a thread
+ * pool and, once complete, continue execution on an associated completion
+ * executor, such as a coroutine's associated executor:
+ * @code boost::asio::awaitable<void> my_coroutine()
+ * {
+ *    // ...
+ *
+ *    int result = co_await boost::asio::post(
+ *        []{
+ *          return perform_expensive_computation();
+ *        },
+ *        my_thread_pool);
+ *
+ *    // handle result on the coroutine's associated executor
+ * } @endcode
+ *
  * @par Completion Signature
  * @code void(decay_t<result_of_t<decay_t<Function>()>>) @endcode
  */