Documentation work

README.md

@@ -69,7 +69,7 @@ create concurrent network programs using callbacks or coroutines.
 
 * **C++11:** Robust support for most language features.
 * **Boost:** Boost.Asio and some other parts of Boost.
-* **OpenSSL:** Optional, for using TLS/Secure sockets.
+* **OpenSSL:** Required for using TLS/Secure sockets and examples/tests
 
 When using Microsoft Visual C++, Visual Studio 2015 Update 3 or later is required.
 
@@ -78,7 +78,26 @@ One of these components is required in order to build the tests and examples:
 * Properly configured bjam/b2
 * CMake 3.5.1 or later (Windows only)
 
-## Branches
+## Building
+
+Beast is header-only. To use it just add the necessary `#include` line
+to your source files, like this:
+```C++
+#include <boost/beast.hpp>
+```
+
+If you use coroutines you'll need to link with the Boost.Coroutine
+library. Please visit the Boost documentation for instructions
+on how to do this for your particular build system.
+
+## GitHub
+
+To use the latest official release of Beast, simply obtain the latest
+Boost distribution and follow the instructions for integrating it
+into your development environment. If you wish to build the examples
+and tests, or if you wish to preview upcoming changes and features,
+it is suggested to clone the "Boost superproject" and work with Beast
+"in-tree" (meaning, the libs/beast subdirectory of the superproject).
 
 The official repository contains the following branches:
 
@@ -94,42 +113,44 @@ branch version of Beast, you should clone the Boost superproject,
 switch to the **master** branch in the superproject and acquire
 all the Boost libraries corresponding to that branch including Beast.
 
-Or, to use the latest shipping version of Beast, simply use it
+To clone the superproject locally, and switch into the main project's
-from the corresponding distribution of Boost.
+directory use:
-
+```
-## Building
+git clone --recursive https://github.com/boostorg/boost.git
-
+cd boost
-Beast is header-only. To use it just add the necessary `#include` line
-to your source files, like this:
-```C++
-#include <boost/beast.hpp>
 ```
 
-If you use coroutines you'll need to link with the Boost.Coroutine
+"bjam" is used to build Beast and the Boost libraries. On a non-Windows
-library. Please visit the Boost documentation for instructions
+system use this command to build bjam:
-on how to do this for your particular build system.
-
-To build the documentation, examples, tests, and benchmarks it is
-necessary to first obtain the Boost "superproject" along with sources of
-all of the Boost libraries, then run the `b2` command to build the Boost
-libraries.
-Instructions for doing so may be found on
-the [Boost Wiki](https://github.com/boostorg/boost/wiki/Getting-Started).
-These commands will build the programs and documentation that come
-with Beast:
-
 ```
-cd boost   # The directory containing the Boost superproject and libraries
+./bootstrap.sh
-b2 libs/beast/test cxxstd=11    # bjam must be in your $PATH
-b2 libs/beast/example cxxstd=11
-b2 libs/beast/doc
 ```
 
-On Windows platforms only, CMake may be used to generate a Visual Studio
+From a Windows command line, build bjam using this command:
-solution and a set of Visual Studio project files using these commands:
+```
+.\BOOTSTRAP.BAT
+```
+
+Make sure the bjam tool (also called "b2") is available in the path
+your shell uses to find executables. The Beast project is located in
+"libs/beast" relative to the directory containing the Boot superproject.
+To build the Beast tests, examples, and documentation use these commands:
+```
+b2 -j2 libs/beast/test cxxstd=11      # bjam must be in your $PATH
+b2 -j2 libs/beast/example cxxstd=11   # "-j2" means use two processors
+b2 libs/beast/doc                     # Doxygen and Saxon are required for this
+```
+
+Additional instructions for configuring, using, and building libraries
+in superproject may be found in the
+[Boost Wiki](https://github.com/boostorg/boost/wiki/Getting-Started).
+
+## Visual Studio
+
+CMake may be used to generate a very nice Visual Studio solution and
+a set of Visual Studio project files using these commands:
 
 ```
-cd boost   # The directory containing the Boost superproject and libraries
 cd libs/beast
 mkdir bin
 cd bin
@@ -145,12 +166,11 @@ The files in the repository are laid out thusly:
     bin/            Create this to hold executables and project files
     bin64/          Create this to hold 64-bit Windows executables and project files
     doc/            Source code and scripts for the documentation
-    include/        Where the header files live
+    include/        Where the header files are located
-    extras/         Additional APIs, may change
     example/        Self contained example programs
     meta/           Metadata for Boost integration
-    scripts/        Small scripts used with CI systems
+    test/           The unit tests for Beast
-    test/           Unit tests
+    tools/          Scripts used for CI testing
 ```
 
 ## Usage

include/boost/beast/websocket/stream_base.hpp

@@ -116,6 +116,12 @@ struct stream_base
         values are selected upon construction, regardless of the
         current or actual role in use on the stream.
 
+        @par Example
+        This statement sets the timeout settings of the stream to
+        the suggested values for the server role:
+        @code
+        @endcode
+
         @param role The role of the websocket stream
         (@ref role_type::client or @ref role_type::server).
     */

test/beast/websocket/CMakeLists.txt

@@ -34,6 +34,7 @@ add_executable (tests-beast-websocket
     rfc6455.cpp
     role.cpp
     stream.cpp
+    stream_base.cpp
     stream_explicit.cpp
     stream_fwd.cpp
     teardown.cpp

test/beast/websocket/Jamfile

@@ -24,6 +24,7 @@ local SOURCES =
     rfc6455.cpp
     role.cpp
     stream.cpp
+    stream_base.cpp
     stream_explicit.cpp
     stream_fwd.cpp
     teardown.cpp

test/beast/websocket/stream_base.cpp

@@ -0,0 +1,38 @@
+//
+// Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/boostorg/beast
+//
+
+// Test that header file is self-contained.
+#include <boost/beast/websocket/stream_base.hpp>
+
+#include <boost/beast/_experimental/unit_test/suite.hpp>
+
+namespace boost {
+namespace beast {
+namespace websocket {
+
+class stream_base_test : public unit_test::suite
+{
+public:
+    void
+    testJavadoc()
+    {
+    }
+
+    void
+    run() override
+    {
+        testJavadoc();
+    }
+};
+
+BEAST_DEFINE_TESTSUITE(beast,websocket,stream_base);
+
+} // websocket
+} // beast
+} // boost

test/doc/websocket_snippets.cpp

@@ -60,96 +60,20 @@ boost::ignore_unused(ec);
 //[ws_snippet_6
     std::string const host = "example.com";
     net::ip::tcp::resolver r{ioc};
-    stream<net::ip::tcp::socket> ws{ioc};
+    stream<tcp_stream<net::io_context::executor_type>> ws{ioc};
     auto const results = r.resolve(host, "ws");
-    net::connect(ws.next_layer(), results.begin(), results.end());
+    connect(get_lowest_layer(ws), results.begin(), results.end());
 //]
 }
 
 {
 //[ws_snippet_7
     net::ip::tcp::acceptor acceptor{ioc};
-    stream<net::ip::tcp::socket> ws{acceptor.get_executor().context()};
+    stream<tcp_stream<net::io_context::executor_type>> ws{acceptor.get_executor().context()};
-    acceptor.accept(ws.next_layer());
+    acceptor.accept(get_lowest_layer(ws).socket());
 //]
 }
 
-{
-    stream<net::ip::tcp::socket> ws{ioc};
-//[ws_snippet_8
-    ws.handshake("localhost", "/");
-//]
-
-//[ws_snippet_9
-    ws.handshake_ex("localhost", "/",
-        [](request_type& m)
-        {
-            m.insert(http::field::sec_websocket_protocol, "xmpp;ws-chat");
-        });
-//]
-
-//[ws_snippet_10
-    response_type res;
-    ws.handshake(res, "localhost", "/");
-    if(! res.count(http::field::sec_websocket_protocol))
-        throw std::invalid_argument("missing subprotocols");
-//]
-
-//[ws_snippet_11
-    ws.accept();
-//]
-
-//[ws_snippet_12
-    ws.accept_ex(
-        [](response_type& m)
-        {
-            m.insert(http::field::server, "MyServer");
-        });
-//]
-}
-
-{
-//[ws_snippet_13]
-    // Buffer required for reading HTTP messages
-    flat_buffer buffer;
-
-    // Read the HTTP request ourselves
-    http::request<http::string_body> req;
-    http::read(sock, buffer, req);
-
-    // See if its a WebSocket upgrade request
-    if(websocket::is_upgrade(req))
-    {
-        // Construct the stream, transferring ownership of the socket
-        stream<net::ip::tcp::socket> ws{std::move(sock)};
-
-        // Clients SHOULD NOT begin sending WebSocket
-        // frames until the server has provided a response.
-        BOOST_ASSERT(buffer.size() == 0);
-
-        // Accept the upgrade request
-        ws.accept(req);
-    }
-    else
-    {
-        // Its not a WebSocket upgrade, so
-        // handle it like a normal HTTP request.
-    }
-//]
-}
-
-{
-    stream<net::ip::tcp::socket> ws{ioc};
-//[ws_snippet_14
-    // Read into our buffer until we reach the end of the HTTP request.
-    // No parsing takes place here, we are just accumulating data.
-    net::streambuf buffer;
-    net::read_until(sock, buffer, "\r\n\r\n");
-
-    // Now accept the connection, using the buffered data.
-    ws.accept(buffer.data());
-//]
-}
 {
     stream<net::ip::tcp::socket> ws{ioc};
 //[ws_snippet_15