Documentation tidying

fix #836

CHANGELOG.md

@@ -1,6 +1,7 @@
 Version 129:
 
 * Add autobahn test report to doc
+* Documentation tidying
 
 --------------------------------------------------------------------------------
 

doc/qbk/00_main.qbk

@@ -26,7 +26,7 @@
 [template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
 [template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']
 
-[template repo_file[path] '''<ulink url="../../'''[path]'''">'''[path]'''</ulink>''']
+[template source_file[path] '''<ulink url="../../'''[path]'''">'''[path]'''</ulink>''']
 [template include_file[path][^<'''<ulink url="../../../../'''[path]'''">'''[path]'''</ulink>'''>]]
 
 [def __N3747__                  [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf [*N3747]]]
@@ -34,14 +34,19 @@
 [def __rfc6455__                [@https://tools.ietf.org/html/rfc6455 rfc6455]]
 [def __rfc7230__                [@https://tools.ietf.org/html/rfc7230 rfc7230]]
 
-[def __Asio__                   [@boost:/doc/html/boost_asio.html Boost.Asio]]
+[def __Asio__                   [@boost:/libs/asio/index.html Boost.Asio]]
 [def __async_initfn__           [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html initiating function]]
 
+[def __get_associated_allocator__   [@boost:/doc/html/boost_asio/reference/get_associated_allocator.html `get_associated_allocator`]]
+[def __get_associated_executor__    [@boost:/doc/html/boost_asio/reference/get_associated_executor.html `get_associated_executor`]]
+
 [def __asio_handler_invoke__    [@boost:/doc/html/boost_asio/reference/asio_handler_invoke.html `asio_handler_invoke`]]
 [def __asio_handler_allocate__  [@boost:/doc/html/boost_asio/reference/asio_handler_allocate.html `asio_handler_allocate`]]
 [def __io_context__             [@boost:/doc/html/boost_asio/reference/io_context.html `boost::asio::io_context`]]
 [def __executor_work_guard__    [@boost:/doc/html/boost_asio/reference/executor_work_guard.html `boost::asio::executor_work_guard`]]
+[def __post__                   [@boost:/doc/html/boost_asio/reference/post.html `boost::asio::post`]]
 [def __socket__                 [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `boost::asio::ip::tcp::socket`]]
+[def __ssl_context__            [@boost:/doc/html/boost_asio/reference/ssl__context.html `boost::asio::ssl::context`]]
 [def __ssl_stream__             [@boost:/doc/html/boost_asio/reference/ssl__stream.html `boost::asio::ssl::stream`]]
 [def __streambuf__              [@boost:/doc/html/boost_asio/reference/streambuf.html `boost::asio::streambuf`]]
 [def __use_future__             [@boost:/doc/html/boost_asio/reference/use_future_t.html `boost::asio::use_future`]]
@@ -73,6 +78,7 @@
 [def __basic_fields__           [link beast.ref.boost__beast__http__basic_fields `basic_fields`]]
 [def __basic_multi_buffer__     [link beast.ref.boost__beast__basic_multi_buffer `basic_multi_buffer`]]
 [def __basic_parser__           [link beast.ref.boost__beast__http__basic_parser `basic_parser`]]
+[def __bind_handler__           [link beast.ref.boost__beast__bind_handler `bind_handler`]]
 [def __buffer_body__            [link beast.ref.boost__beast__http__buffer_body `buffer_body`]]
 [def __fields__                 [link beast.ref.boost__beast__http__fields `fields`]]
 [def __flat_buffer__            [link beast.ref.boost__beast__flat_buffer `flat_buffer`]]

doc/qbk/01_intro.qbk

@@ -27,8 +27,9 @@ This library is designed for:
 
 * [*Basis for Further Abstraction.] Components are well-suited for building upon.
 
-Beast is not an HTTP client or HTTP server, but it can be used to build
+This library is not a client or server, but it can be used to build those
-those things.
+things. Many examples are provided, including clients and servers, which may
+be used as a starting point for writing your own program.
 
 [heading Motivation]
 
@@ -60,11 +61,11 @@ Supported compilers: msvc-14+, gcc 4.8+, clang 3.6+
 
 Sources are [*header-only].
 To link a program using Beast successfully, add the
-[@http://www.boost.org/libs/system/doc/reference.html Boost.System]
+[@boost:/libs/system/index.html Boost.System]
 library to your build scripts. If you use coroutines you'll also need the
-[@http://www.boost.org/libs/coroutine/doc/html/index.html Boost.Coroutine]
+[@boost:/libs/coroutine/index.html Boost.Coroutine]
 library. Please visit the
-[@http://www.boost.org/doc/ Boost documentation]
+[@boost:/more/getting_started.html Boost documentation]
 for instructions on how to do this for your particular build system.
 
 [heading Credits]
@@ -102,7 +103,9 @@ for tirelessly answering questions on
 
 [section WebSocket]
 
-The Autobahn|Testsuite provides a fully automated test suite to
+The
+[@https://github.com/crossbario/autobahn-testsuite Autobahn WebSockets Testsuite]
+provides a fully automated test suite to
 verify client and server implementations of The WebSocket Protocol
 for specification conformance and implementation robustness.
 The test suite will check an implementation by doing basic
@@ -114,16 +117,14 @@ contains over 500 test cases.
 [@https://vinniefalco.github.io/boost/beast/reports/autobahn/index.html Autobahn|Testsuite WebSocket Results]
 
 [warning
-    Version 0.7.6 of
+    Version 0.7.6 of Autobahn|Testsuite contains a
-    [@https://github.com/crossbario/autobahn-testsuite Autobahn WebSockets Testsuite]
-    contains a
     [@https://github.com/crossbario/autobahn-testsuite/issues/77 known defect]
-    which causes false positives for the following test cases:
+    which causes false positive failures in Beast for the following test cases:
     { 12.4.5, 12.4.6, 12.4.8, 12.4.9, 12.4.10, 12.4.11, 12.4.13,
       12.4.14, 12.4.15, 12.4.16, 12.4.17, 12.4.18 }
+    When this issue is resolved in the test suite, the reports will be updated.
 ]
 
-
 [endsect]
 
 [endsect]

doc/qbk/02_examples.qbk

@@ -12,13 +12,13 @@
 
 These complete programs are intended to quickly impress upon readers
 the flavor of the library. Source code and build scripts for them are
-located in the example/ directory.
+located in the [source_file example] directory.
 
 [section HTTP Client]
 
 Use HTTP to make a GET request to a website and print the response:
 
-File: [repo_file example/http/client/sync/http_client_sync.cpp]
+File: [source_file example/http/client/sync/http_client_sync.cpp]
 
 [example_http_client]
 
@@ -28,7 +28,7 @@ File: [repo_file example/http/client/sync/http_client_sync.cpp]
 
 Establish a WebSocket connection, send a message and receive the reply:
 
-File: [repo_file example/websocket/client/sync/websocket_client_sync.cpp]
+File: [source_file example/websocket/client/sync/websocket_client_sync.cpp]
 
 [example_websocket_client]
 
@@ -42,7 +42,7 @@ File: [repo_file example/websocket/client/sync/websocket_client_sync.cpp]
 [block'''<?dbhtml stop-chunking?>''']
 
 Source code and build scripts for these programs are located
-in the [repo_file example] directory.
+in the [source_file example] directory.
 
 
 
@@ -203,7 +203,7 @@ listed here along with a description of their use:
 [table
 [[Source File] [Description]]
 [
-    [[repo_file example/common/detect_ssl.hpp]]
+    [[source_file example/common/detect_ssl.hpp]]
     [
         This contains the detect SSL algorithm including the
         synchronous and asynchronous initiating functions, described
@@ -211,7 +211,7 @@ listed here along with a description of their use:
         support both plain and SSL sessions on the same port.
     ]
 ][
-    [[repo_file example/common/root_certificates.hpp]]
+    [[source_file example/common/root_certificates.hpp]]
     [
         This contains the root SSL certificates used in the SSL client
         examples. These certificates are used to verify the signatures
@@ -221,7 +221,7 @@ listed here along with a description of their use:
         possible server.
     ]
 ][
-    [[repo_file example/common/server_certificate.hpp]]
+    [[source_file example/common/server_certificate.hpp]]
     [
         This file contains a self-signed SSL certificate used by the
         SSL server examples. It has not been validated by a Certificate
@@ -229,10 +229,10 @@ listed here along with a description of their use:
         a browser may generate security warnings.
     ]
 ][
-    [[repo_file example/common/ssl_stream.hpp]]
+    [[source_file example/common/ssl_stream.hpp]]
     [
-        The `ssl_stream` is a replacement for `boost::asio::ssl::stream`
+        The `ssl_stream` is a replacement for __ssl_stream__ which
-        which supports construction from a moved-froms ocket and is also
+        supports construction from a moved-froms ocket and is also
         itself move constructible.
     ]
 ]]
@@ -247,7 +247,7 @@ Here are all of the example functions and classes presented
 throughout the documentation, they can be included and used
 in your program without modification
 
-* [repo_file example/doc/http_examples.hpp]
+* [source_file example/doc/http_examples.hpp]
 
 [endsect]
 
@@ -261,7 +261,7 @@ operation implementation. This is a complete, runnable version of
 the example described in
 [link beast.using_io.writing_composed_operations.echo Writing Composed Operations: Echo].
 
-* [repo_file example/echo-op/echo_op.cpp]
+* [source_file example/echo-op/echo_op.cpp]
 
 [endsect]
 

doc/qbk/03_core/5_composed.qbk

@@ -45,9 +45,8 @@ composed operations:
     invoked with no arguments invokes the original completion handler with a
     list of bound arguments. The invocation is made from the same implicit
     or explicit strand as that which would be used to invoke the original
-    handler. This is accomplished by using the correct overload of
+    handler. This works because the returned call wrapper uses the same
-    `asio_handler_invoke` associated with the original completion handler.
+    associated executor and associated allocator as the bound handler.
-
 ]]
 [[
     [link beast.ref.boost__beast__handler_ptr `handler_ptr`]
@@ -115,54 +114,15 @@ this echo operation:
 
 This is the most important element of writing a composed operation, and
 the part which is often neglected or implemented incorrectly. It is the
-declaration and definition of the "handler hooks". There are four hooks:
+forwarding of the final handler's associated allocator and associated
-
+executor to the composed operation.
-[table Handler Hooks
-[[Name][Description]]
-[[
-    [@boost:/doc/html/boost_asio/reference/asio_handler_invoke.html `asio_handler_invoke`]
-][
-    Default invoke function for handlers. This hooking function ensures
-    that the invoked method used for the final handler is accessible at
-    each intermediate step.
-]]
-[[
-    [@boost:/doc/html/boost_asio/reference/asio_handler_allocate.html `asio_handler_allocate`]
-][
-    Default allocation function for handlers. Implement `asio_handler_allocate`
-    and `asio_handler_deallocate` for your own handlers to provide custom
-    allocation for temporary objects.
-]]
-[[
-    [@boost:/doc/html/boost_asio/reference/asio_handler_deallocate.html `asio_handler_deallocate`]
-][
-    Default deallocation function for handlers. Implement `asio_handler_allocate`
-    and `asio_handler_deallocate` for your own handlers to provide custom
-    allocation for temporary objects.
-]]
-[[
-    [@boost:/doc/html/boost_asio/reference/asio_handler_is_continuation.html `asio_handler_is_continuation`]
-][
-    Default continuation function for handlers. Implement
-    `asio_handler_is_continuation` for your own handlers to indicate when
-    a handler represents a continuation.
-]]
-]
 
 Our composed operation stores the final handler and performs its own
 intermediate asynchronous operations. To ensure that I/O objects, in this
-case the stream, are accessed safely it is important to use the same method
+case the stream, are accessed safely it is important to use the same
-to invoke intermediate handlers as that used to invoke the final handler.
+executor to invoke intermediate handlers as that used to invoke the final
-Similarly, for the memory allocation hooks our composed operation should use
+handler. Similarly, for memory allocations our composed operation should
-the same hooks as those used by the final handler. And finally for the
+use the allocator associated with the final handler.
-`asio_is_continuation` hook, we want to return `true` for any intermediate
-asynchronous operations we perform after the first one, since those represent
-continuations. For the first asynchronous operation we perform, the hook should
-return `true` only if the final handler also represents a continuation. Our
-implementation of the hooks will forward the call to the corresponding
-overloads of the final handler:
-
-[example_core_echo_op_6]
 
 There are some common mistakes that should be avoided when writing
 composed operations:
@@ -180,20 +140,17 @@ composed operations:
   composed operation. This will cause undefined behavior. For example,
   if someone  calls the initiating function with a strand-wrapped
   function object, and there is more than thread running on the
-  `io_context`, the underlying stream may be accessed in a fashion
+  __io_context__, the underlying stream may be accessed in a fashion
   that violates safety guarantees.
 
 * For operations which complete immediately (i.e. without calling an
-  intermediate initiating function), forgetting to use
+  intermediate initiating function), forgetting to use __post__ to
-  [@boost:/doc/html/boost_asio/reference/post.html `boost::asio::post`]
+  invoke the final handler. This breaks the following initiating
-  to invoke the final handler. This breaks the following initiating
   function guarantee: ['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::post`].
+  in a manner equivalent to using __post__]. The function
-  The function
+  __bind_handler__ is provided for this purpose.
-  [link beast.ref.boost__beast__bind_handler `bind_handler`]
-  is provided for this purpose.
 
 A complete, runnable version of this example may be found in the examples
 directory.

doc/qbk/04_http/02_message.qbk

@@ -57,8 +57,8 @@ inspection of fields. As per __rfc7230__, a non-case-sensitive comparison
 is used for field names. User defined types for fields are possible.
 The `Body` type determines the type of the container used to represent the
 body as well as the algorithms for transferring buffers to and from the
-the container. The library comes with a collection of common body types.
+container. The library comes with a collection of common body types. As
-As with fields, user defined body types are possible.
+with fields, user defined body types are possible.
 
 Sometimes it is desired to only work with a header. Beast provides a single
 class template __header__ and some aliases to model HTTP/1 and HTTP/2 headers:

doc/qbk/04_http/04_serializer_streams.qbk

@@ -14,15 +14,13 @@ at once, such as:
 
 * Send the header first, and the body later.
 
-* Set chunk extensions or trailers using a chunk decorator.
-
 * Send a message incrementally: bounded work in each I/O cycle.
 
 * Use a series of caller-provided buffers to represent the body.
 
 These tasks may be performed by using the serializer stream interfaces.
-To use these interfaces, first construct a suitable object with
+To use these interfaces, first construct an appropriate serializer
-the message to be sent:
+from the message to be sent:
 
 [table Serializer
 [[Name][Description]]

doc/qbk/04_http/06_serializer_buffers.qbk

@@ -16,8 +16,8 @@ algorithms on objects whose interface does not conform to __Stream__.
 For example, a
 [@https://github.com/libuv/libuv *libuv* socket].
 The serializer interface is interactive; the caller invokes it repeatedly
-to produce buffers until all of the buffers have been generated. Then the
+to produce buffers until all of the serialized octets have been generated.
-serializer is destroyed.
+Then the serializer is destroyed.
 
 To obtain the serialized next buffer sequence, call
 [link beast.ref.boost__beast__http__serializer.next `serializer::next`].

doc/qbk/04_http/09_custom_body.qbk

@@ -70,10 +70,10 @@ the body type as it appears in the message. This can be any type. For
 example, a body's value type may specify `std::vector<char>` or even
 `std::list<std::string>`. A custom body may even set the value type to
 something that is not a container for body octets, such as a
-[@http://www.boost.org/libs/filesystem/doc/reference.html#class-path `boost::filesystem::path`].
+[@boost:/libs/filesystem/doc/reference.html#class-path `boost::filesystem::path`].
 Or, a more structured container may be chosen. This declares a body's
 value type as a JSON tree structure produced from a
-[@boost:/doc/html/property_tree/parsers.html#property_tree.parsers.json_parser `json_parser`]:
+[@boost:/doc/html/property_tree/parsers.html#property_tree.parsers.json_parser `boost::property_tree::json_parser`]:
 ```
 #include <boost/property_tree/ptree.hpp>
 #include <boost/property_tree/json_parser.hpp>

doc/qbk/04_http/10_custom_parsers.qbk

@@ -11,13 +11,14 @@
 
 While the parsers included in the library will handle a broad number of
 use-cases, the __basic_parser__ interface can be subclassed to implement
-custom parsing strategies: the basic parser processes the incoming octets
+custom strategies for storing parsed results: the basic parser processes
-into elements according to the HTTP/1 protocol specification, while the
+the incoming octets into elements according to the HTTP/1 protocol
-derived class decides what to do with those elements. In particular, users
+specification, while the derived class decides what to do with those
-who create exotic containers for [*Fields] may need to also create their
+elements. In particular, users who create exotic containers for [*Fields]
-own parser. Custom parsers will work with all of the stream read operations
+may need to also create their own parser. Custom parsers will work with
-that work on parsers, as those algorithms use only the basic parser
+all of the stream read operations that work on parsers, as those algorithms
-interface. Some use cases for implementing custom parsers are:
+use only the basic parser interface. Some use cases for implementing custom
+parsers are:
 
 * Inspect incoming header fields and keep or discard them.
 
@@ -25,8 +26,8 @@ interface. Some use cases for implementing custom parsers are:
 
 * Store header data in a user-defined __Fields__ type.
 
-The basic parser uses the Curiously Recurring Template Pattern
+The basic parser uses the
-([@https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern CRTP]).
+[@https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern Curiously Recurring Template Pattern].
 To declare your user defined parser, derive it from __basic_parser__.
 The interface to the parser is event-driven. Member functions of the derived
 class (termed "callbacks" in this context) are invoked with parsed elements

doc/qbk/06_websocket/1_streams.qbk

@@ -26,9 +26,10 @@ socket's constructor:
 
 [heading Using SSL]
 
-To use WebSockets over SSL, use an instance of the `boost::asio::ssl::stream`
+To use WebSockets over SSL, use an instance of the __ssl_stream__
-class template as the template type for the stream. The required `io_context`
+class template as the template type for the stream. The required
-and `ssl::context` arguments are forwarded to the wrapped stream's constructor:
+__io_context__ and __ssl_context__ arguments are forwarded to the
+wrapped stream's constructor:
 
 [wss_snippet_1]
 [wss_snippet_2]

doc/qbk/06_websocket/2_connect.qbk

@@ -28,7 +28,8 @@ the TCP/IP socket:
 [wss_snippet_3]
 
 [note
-    Examples use synchronous interfaces for clarity of exposition.
+    Examples use synchronous interfaces for clarity of exposition;
+    signatures for asynchronous operations are also provided.
 ]
 
 [endsect]

doc/qbk/06_websocket/5_messages.qbk

@@ -9,8 +9,8 @@
 
 [section Send and Receive Messages]
 
-Interfaces for transacting messages are structured into a couple of
+Interfaces for transacting messages are structured into layers. The
-layers. The highest layer provides ease of use, while lower layers provide
+highest layer provides ease of use, while lower layers provide
 additional control and flexibility. The layers are arranged thusly:
 
 [table
@@ -75,7 +75,7 @@ message ahead of time:
 * Sending a message that does not fit in memory at once.
 * Providing incremental results as they become available.
 
-For these cases, the frame oriented interface may be used. This
+For these cases, the partial data oriented interface may be used. This
 example reads and echoes a complete message using this interface:
 
 [ws_snippet_16]

doc/qbk/06_websocket/8_notes.qbk

@@ -65,9 +65,9 @@ However, this code is well-formed:
 
 [ws_snippet_25]
 
-The implementation uses composed asynchronous operations internally;
+The implementation uses composed asynchronous operations; although
-although some individiual operations can perform both reads and writes,
+some individiual operations can perform both reads and writes, this
-this behavior is coordinated internally to make sure the underlying stream
+behavior is coordinated internally to make sure the underlying stream
 is operated in a safe fashion. This allows an asynchronous read operation
 to respond to a received ping frame even while a user-initiated call to
 asynchronous write is active.

doc/qbk/07_concepts/Body.qbk

@@ -24,8 +24,8 @@ the algorithms used during parsing and serialization.
 In this table:
 
 * `B` is a type meeting the requirements of [*Body].
-* `m` is a value of type `message<b, B, F>` where `b` is a `bool` value
+* `m` is a value of type `message<b,B,F>` where `b` is a `bool` value
-  and `F` is a type meeting the requirements of [*Fields].
+  and `F` is a type meeting the requirements of __Fields__.
 
 [table Valid expressions
 [[Expression] [Type] [Semantics, Pre/Post-conditions]]
@@ -66,8 +66,8 @@ In this table:
     [`std::uint64_t`]
     [
         This static member function is optional. It returns the payload
-        size of `body` not including any chunked transfer encoding. The
+        size of `body` in bytes not including any chunked transfer encoding.
-        function shall not exit via an exception.
+        The function shall not exit via an exception.
 
         When this function is present:
 

doc/qbk/07_concepts/BodyReader.qbk

@@ -9,7 +9,9 @@
 
 [section:BodyReader BodyReader]
 
-A [*BodyReader] provides an online algorithm to obtain a sequence of zero
+A [*BodyReader] provides an
+[@https://en.wikipedia.org/wiki/Online_algorithm online algorithm]
+to obtain a sequence of zero
 or more buffers from a body during serialization. The implementation creates
 an instance of this type when needed, and calls into it one or more times to
 retrieve buffers holding body octets. The interface of [*BodyReader] is

doc/qbk/08_design.qbk

@@ -52,6 +52,20 @@ start. Other design goals:
 
 * Allow for customizations, if the user needs it.
 
+The following video presentation was delivered at
+[@https://cppcon.org/ CppCon]
+in 2016. It provides a light introduction to some of the earliest
+interfaces of Beast (which have since changed).
+
+[block'''
+<mediaobject>
+  <videoobject>
+    <videodata fileref="https://www.youtube.com/embed/uJZgRcvPFwI?rel=0"
+        align="center" contentwidth="560" contentdepth="315"/>
+  </videoobject>
+</mediaobject>
+''']
+
 [include 08_design/1_http_message.qbk]
 [include 08_design/2_http_comparison.qbk]
 [include 08_design/3_websocket_zaphoyd.qbk]

doc/qbk/08_design/1_http_message.qbk

@@ -5,10 +5,28 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
     Official repository: https://github.com/boostorg/beast
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/WsUnnYEKPnI?rel=0" frameborder="0" allowfullscreen></iframe>
 ]
 
 [section HTTP Message Container]
 
+The following video presentation was delivered at
+[@https://cppcon.org/ CppCon]
+in 2017. The presentation provides a simplified explanation of the design
+process for the HTTP message container used in Beast. The slides and code
+used are available in the
+[@https://github.com/vinniefalco/CppCon2017 GitHub repository].
+
+[block'''
+<mediaobject>
+  <videoobject>
+    <videodata fileref="https://www.youtube.com/embed/WsUnnYEKPnI?rel=0"
+        align="center" contentwidth="560" contentdepth="315"/>
+  </videoobject>
+</mediaobject>
+''']
+
 In this section we describe the problem of modeling HTTP messages and explain
 how the library arrived at its solution, with a discussion of the benefits
 and drawbacks of the design choices. The goal for creating a message model

example/echo-op/echo_op.cpp

@@ -145,7 +145,7 @@ public:
     // Associated allocator support. This is Asio's system for
     // allowing the final completion handler to customize the
     // memory allocation strategy used for composed operation
-    // states. A composed operation needs to use the same allocator
+    // states. A composed operation should use the same allocator
     // as the final handler. These declarations achieve that.
 
     using allocator_type =
@@ -172,11 +172,6 @@ public:
             p_.handler(), p_->stream.get_executor());
     }
 
-    // (DEPRECATED)
-    template<class AsyncStream_, class Handler_>
-    friend bool  asio_handler_is_continuation(
-        echo_op<AsyncStream_, Handler_>* op);
-
     // The entry point for this handler. This will get called
     // as our intermediate operations complete. Definition below.
     //
@@ -237,33 +232,6 @@ operator()(boost::beast::error_code ec, std::size_t bytes_transferred)
 
 //]
 
-//[example_core_echo_op_6
-
-// Determines if the next asynchronous operation represents a
-// continuation of the asynchronous flow of control associated
-// with the final handler. If we are past step one, it means
-// we have performed an asynchronous operation therefore any
-// subsequent operation would represent a continuation.
-// Otherwise, we propagate the handler's associated value of
-// is_continuation. Getting this right means the implementation
-// may schedule the invokation of the invoked functions more
-// efficiently.
-//
-template<class AsyncStream, class Handler>
-bool asio_handler_is_continuation(echo_op<AsyncStream, Handler>* op)
-{
-    // This next call is structured to permit argument
-    // dependent lookup to take effect.
-    using boost::asio::asio_handler_is_continuation;
-
-    // Always use std::addressof to pass the pointer to the handler,
-    // otherwise an unwanted overload of operator& may be called instead.
-    return op->p_->step > 1 ||
-        asio_handler_is_continuation(std::addressof(op->p_.handler()));
-}
-
-//]
-
 //[example_core_echo_op_3
 
 template<class AsyncStream, class Handler>

include/boost/beast/http/impl/message.ipp

@@ -403,7 +403,7 @@ prepare_payload(std::false_type)
         this->result() == status::not_modified))
     {
         if(! n || *n > 0)
-            // The response body MUST BE empty for this case
+            // The response body MUST be empty for this case
             BOOST_THROW_EXCEPTION(std::invalid_argument{
                 "invalid response body"});
     }