Tidy up some documentation

fix #984

CHANGELOG.md

@@ -5,6 +5,7 @@ Version 158:
 * Examples set reuse_address(true)
 * Advanced servers support clean shutdown via SIGINT or SIGTERM
 * DynamicBuffer input areas are not mutable
+* Tidy up some documentation
 
 --------------------------------------------------------------------------------
 

doc/qbk/03_core/5_composed.qbk

@@ -41,24 +41,27 @@ composed operations:
 [[
     [link beast.ref.boost__beast__bind_handler `bind_handler`]
 ][
-    This function returns a new, nullary completion handler which when
+    This function creates a new handler which, when invoked, calls
-    invoked with no arguments invokes the original completion handler with a
+    the original handler with the list of bound arguments. Any
-    list of bound arguments. The invocation is made from the same implicit
+    parameters passed in the invocation will be substituted for
-    or explicit strand as that which would be used to invoke the original
+    placeholders present in the list of bound arguments. Parameters
-    handler. This works because the returned call wrapper uses the same
+    which are not matched to placeholders are silently discarded.
-    associated executor and associated allocator as the bound handler.
+
+    The passed handler and arguments are forwarded into the returned
+    handler, whose associated allocator and associated executor will
+    will be the same as those of the original handler.
 ]]
 [[
     [link beast.ref.boost__beast__handler_ptr `handler_ptr`]
 ][
     This is a smart pointer container used to manage the internal state of a
     composed operation. It is useful when the state is non trivial. For example
-    when the state has non-copyable or expensive to copy types. The container
+    when the state has non-movable or contains expensive to move types. The
-    takes ownership of the final completion handler, and provides boilerplate
+    container takes ownership of the final completion handler, and provides
-    to invoke the final handler in a way that also deletes the internal state.
+    boilerplate to invoke the final handler in a way that also deletes the
-    The internal state is allocated using the final completion handler's
+    internal state. The internal state is allocated using the final completion
-    associated allocator, benefiting from all handler memory management
+    handler's associated allocator, benefiting from all handler memory
-    optimizations transparently.
+    management optimizations transparently.
 ]]
 ]
 

include/boost/beast/core/bind_handler.hpp

@@ -31,11 +31,6 @@ namespace beast {
     handler, whose associated allocator and associated executor will
     will be the same as those of the original handler.
 
-    Unlike `boost::asio::io_context::wrap`, the returned handler can
-    be used in a subsequent call to `boost::asio::post` instead of
-    `boost::asio::dispatch`, to ensure that the handler will not be
-    invoked immediately by the calling function.
-
     Example:
 
     @code