Documentation work

CHANGELOG.md

@@ -2,6 +2,7 @@ Version 195:
 
 * net is a namespace alias for boost::asio
 * Simplify multi_buffer and static_buffer sequences
+* Documentation work
 
 --------------------------------------------------------------------------------
 

doc/qbk/00_main.qbk

@@ -40,17 +40,17 @@
 [def __asio_handler_allocate__  [@boost:/doc/html/boost_asio/reference/asio_handler_allocate.html `asio_handler_allocate`]]
 [def __asio_handler_invoke__    [@boost:/doc/html/boost_asio/reference/asio_handler_invoke.html `asio_handler_invoke`]]
 [def __deduced__                [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html#boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]]
-[def __executor_work_guard__    [@boost:/doc/html/boost_asio/reference/executor_work_guard.html `boost::asio::executor_work_guard`]]
+[def __executor_work_guard__    [@boost:/doc/html/boost_asio/reference/executor_work_guard.html `net::executor_work_guard`]]
-[def __get_associated_allocator__   [@boost:/doc/html/boost_asio/reference/get_associated_allocator.html `get_associated_allocator`]]
+[def __get_associated_allocator__   [@boost:/doc/html/boost_asio/reference/get_associated_allocator.html `net::get_associated_allocator`]]
-[def __get_associated_executor__    [@boost:/doc/html/boost_asio/reference/get_associated_executor.html `get_associated_executor`]]
+[def __get_associated_executor__    [@boost:/doc/html/boost_asio/reference/get_associated_executor.html `net::get_associated_executor`]]
-[def __io_context__             [@boost:/doc/html/boost_asio/reference/io_context.html `boost::asio::io_context`]]
+[def __io_context__             [@boost:/doc/html/boost_asio/reference/io_context.html `net::io_context`]]
-[def __post__                   [@boost:/doc/html/boost_asio/reference/post.html `boost::asio::post`]]
+[def __post__                   [@boost:/doc/html/boost_asio/reference/post.html `net::post`]]
-[def __socket__                 [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `boost::asio::ip::tcp::socket`]]
+[def __socket__                 [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `tcp::socket`]]
-[def __ssl_context__            [@boost:/doc/html/boost_asio/reference/ssl__context.html `boost::asio::ssl::context`]]
+[def __ssl_context__            [@boost:/doc/html/boost_asio/reference/ssl__context.html `net::ssl::context`]]
-[def __ssl_stream__             [@boost:/doc/html/boost_asio/reference/ssl__stream.html `boost::asio::ssl::stream`]]
+[def __ssl_stream__             [@boost:/doc/html/boost_asio/reference/ssl__stream.html `net::ssl::stream`]]
-[def __streambuf__              [@boost:/doc/html/boost_asio/reference/streambuf.html `boost::asio::streambuf`]]
+[def __streambuf__              [@boost:/doc/html/boost_asio/reference/streambuf.html `net::streambuf`]]
-[def __use_future__             [@boost:/doc/html/boost_asio/reference/use_future_t.html `boost::asio::use_future`]]
+[def __use_future__             [@boost:/doc/html/boost_asio/reference/use_future_t.html `net::use_future`]]
-[def __yield_context__          [@boost:/doc/html/boost_asio/reference/yield_context.html `boost::asio::yield_context`]]
+[def __yield_context__          [@boost:/doc/html/boost_asio/reference/yield_context.html `net::yield_context`]]
 
 [def __AsyncReadStream__        [@boost:/doc/html/boost_asio/reference/AsyncReadStream.html [*AsyncReadStream]]]
 [def __AsyncWriteStream__       [@boost:/doc/html/boost_asio/reference/AsyncWriteStream.html [*AsyncWriteStream]]]

doc/qbk/01_intro.qbk

@@ -60,16 +60,27 @@ Beast requires:
 * [*Boost:] Beast only works with Boost, not stand-alone Asio
 * [*OpenSSL:] Optional, for using TLS/Secure sockets.
 
-Supported compilers: msvc-14+, gcc 4.8+, clang 3.6+
+Tested with these compilers: msvc-14+, gcc 4.8.4+, clang 3.6+.
 
-Sources are [*header-only].
+Sources are [*header-only]. Adding additional libraries to the
-To link a program using Beast successfully, add the
+linking step for your programs to use Beast is normally not
-[@boost:/libs/system/index.html Boost.System]
+necessary, except for these cases:
-library to your build scripts. If you use coroutines you'll also need the
+
+* When using coroutines created by calling 
+[@boost:/doc/html/boost_asio/reference/spawn.html `boost::asio::spawn`],
+you will need to add the
 [@boost:/libs/coroutine/index.html Boost.Coroutine]
-library. Please visit the
+library to your program.
-[@boost:/more/getting_started.html Boost documentation]
+
-for instructions on how to do this for your particular build system.
+* When using
+[@boost:/doc/html/boost_asio/reference/ssl__stream.html `boost::asio::ssl::stream`],
+you will need to add the
+[@https://www.openssl.org/ OpenSSL]
+library to your program.
+
+Please visit the [@boost:/more/getting_started.html Boost documentation]
+for instructions on how to build and link with Boost libraries for your
+particular environment system.
 
 [endsect]
 
@@ -115,8 +126,8 @@ Many thanks to
 [@http://www.boost.org/users/people/glen_fernandes.html Glen Fernandes],
 and
 [@https://github.com/pdimov Peter Dimov]
-for tirelessly answering questions on
+for tirelessly answering questions on the
-[@https://cpplang.slack.com/ Cpplang-Slack].
+[@https://slack.cpp.al/ C++ Language Slack Workspace].
 
 Thanks to
 [@https://github.com/djarek Damian Jarek]
@@ -126,58 +137,4 @@ for his generous participation and source code contributions.
 
 
 
-[section Reports]
+[include 01_intro/1_reports.qbk]
-[block'''<?dbhtml stop-chunking?>''']
-
-[section Security Review (Bishop Fox)]
-
-Since 2005, [@https://www.bishopfox.com/ Bishop Fox] has provided
-security consulting services to the Fortune 1000, high-tech startups,
-and financial institutions worldwide.
-Beast engaged Bishop Fox to assess the security of the Boost C++ Beast HTTP/S
-networking library. The following report details the findings identified during
-the course of the engagement, which started on September 11, 2017.
-
-The assessment team conducted a hybrid application assessment of the Beast
-library. Bishop Fox’s hybrid application assessment methodology leverages
-the real-world attack techniques of application penetration testing in
-combination with targeted source code review to thoroughly identify
-application security vulnerabilities. These fullknowledge assessments
-begin with automated scans of the deployed application and source code.
-Next, analyses of the scan results are combined with manual review to
-thoroughly identify potential application security vulnerabilities. In
-addition, the team performs a review of the application architecture and
-business logic to locate any design-level issues. Finally, the team performs
-manual exploitation and review of these issues to validate the findings.
-
-[@https://vinniefalco.github.io/BeastAssets/Beast%20-%20Hybrid%20Application%20Assessment%202017%20-%20Assessment%20Report%20-%2020171114.pdf [*Beast - Hybrid Application Assessment 2017]]
-
-[block'''
-<mediaobject>
-  <videoobject>
-    <videodata fileref="https://www.youtube.com/embed/4TtyYbGDAj0?rel=0"
-        align="center" contentwidth="560" contentdepth="315"/>
-  </videoobject>
-</mediaobject>
-''']
-
-[endsect]
-
-[section WebSocket (Autobahn|Testsuite)]
-
-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
-WebSocket conversations, extensive protocol compliance
-verification and performance and limits testing.
-Autobahn|Testsuite is used across the industry and
-contains over 500 test cases.
-
-[@https://vinniefalco.github.io/BeastAssets/reports/autobahn/index.html [*Autobahn|Testsuite WebSocket Results]]
-
-[endsect]
-
-[endsect]

doc/qbk/01_intro/1_reports.qbk

@@ -0,0 +1,70 @@
+[/
+    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
+]
+
+[section Reports]
+[block'''<?dbhtml stop-chunking?>''']
+
+
+
+[section Security Review (Bishop Fox)]
+
+Since 2005, [@https://www.bishopfox.com/ Bishop Fox] has provided
+security consulting services to the Fortune 1000, high-tech startups,
+and financial institutions worldwide.
+Beast engaged Bishop Fox to assess the security of the Boost C++ Beast HTTP/S
+networking library. The following report details the findings identified during
+the course of the engagement, which started on September 11, 2017.
+
+The assessment team conducted a hybrid application assessment of the Beast
+library. Bishop Fox’s hybrid application assessment methodology leverages
+the real-world attack techniques of application penetration testing in
+combination with targeted source code review to thoroughly identify
+application security vulnerabilities. These fullknowledge assessments
+begin with automated scans of the deployed application and source code.
+Next, analyses of the scan results are combined with manual review to
+thoroughly identify potential application security vulnerabilities. In
+addition, the team performs a review of the application architecture and
+business logic to locate any design-level issues. Finally, the team performs
+manual exploitation and review of these issues to validate the findings.
+
+[@https://vinniefalco.github.io/BeastAssets/Beast%20-%20Hybrid%20Application%20Assessment%202017%20-%20Assessment%20Report%20-%2020171114.pdf [*Beast - Hybrid Application Assessment 2017]]
+
+[block'''
+<mediaobject>
+  <videoobject>
+    <videodata fileref="https://www.youtube.com/embed/4TtyYbGDAj0?rel=0"
+        align="center" contentwidth="560" contentdepth="315"/>
+  </videoobject>
+</mediaobject>
+''']
+
+[endsect]
+
+
+
+[section WebSocket (Autobahn|Testsuite)]
+
+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
+WebSocket conversations, extensive protocol compliance
+verification and performance and limits testing.
+Autobahn|Testsuite is used across the industry and
+contains over 500 test cases.
+
+[@https://vinniefalco.github.io/BeastAssets/reports/autobahn/index.html [*Autobahn|Testsuite WebSocket Results]]
+
+[endsect]
+
+
+
+[endsect]

doc/qbk/03_core.qbk

@@ -7,7 +7,7 @@
     Official repository: https://github.com/boostorg/beast
 ]
 
-[section:using_io Using I/O]
+[section:using_io Using Core Facilities]
 
 This library makes I/O primitives used by the implementation publicly
 available so users can take advantage of them in their own libraries.
@@ -16,6 +16,8 @@ and helpers for implementing asynchronous operations compatible with
 __Asio__ and described in __N3747__. This section lists these facilities
 by group, with descriptions.
 
+[section Aliases and Abbreviations]
+
 [important
     This documentation assumes familiarity with __Asio__. Sample
     code and identifiers used throughout are written as if the
@@ -25,6 +27,8 @@ by group, with descriptions.
     [snippet_core_1b]
 ]
 
+[endsect]
+
 [include 03_core/1_asio.qbk]
 [include 03_core/2_streams.qbk]
 [include 03_core/3_buffers.qbk]

doc/qbk/03_core/1_asio.qbk

@@ -7,7 +7,7 @@
     Official repository: https://github.com/boostorg/beast
 ]
 
-[section Asio Refresher]
+[section:asio_refresher Networking Refresher]
 
 [warning
     Beast does not manage sockets, make outgoing connections,
@@ -18,8 +18,8 @@
 ]
 
 Library stream algorithms require a __socket__, __ssl_stream__, or other
-__Stream__ object that has already established communication with an
+__Stream__ object that has already established communication with a remote
-endpoint. This example is provided as a reminder of how to work with
+peer. This example is provided as a reminder of how to work with
 sockets:
 
 [snippet_core_2]
@@ -39,21 +39,21 @@ special meaning:
     [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html [*`sock`]]
 ][
     A variable of type
-    [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `boost::asio::ip::tcp::socket`]
+    [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `tcp::socket`]
     which has already been connected to a remote host.
 ]]
 [[
     [@boost:/doc/html/boost_asio/reference/ssl__stream.html [*`ssl_sock`]]
 ][
     A variable of type
-    [@boost:/doc/html/boost_asio/reference/ssl__stream.html `boost::asio::ssl::stream<boost::asio::ip::tcp::socket>`]
+    [@boost:/doc/html/boost_asio/reference/ssl__stream.html `net::ssl::stream<tcp::socket>`]
     which is already connected and has handshaked with a remote host.
 ]]
 [[
     [link beast.ref.boost__beast__websocket__stream [*`ws`]]
 ][
     A variable of type
-    [link beast.ref.boost__beast__websocket__stream `websocket::stream<boost::asio::ip::tcp::socket>`]
+    [link beast.ref.boost__beast__websocket__stream `websocket::stream<tcp::socket>`]
     which is already connected with a remote host.
 ]]
 ]

doc/qbk/03_core/2_streams.qbk

@@ -9,13 +9,12 @@
 
 [section Stream Types]
 
-A __Stream__ is a communication channel where data is transferred as
+A __Stream__ is a communication channel where data is reliably transferred as
-an ordered sequence of octet buffers. Streams are either synchronous
+an ordered sequence of bytes. Streams are either synchronous or asynchronous,
-or asynchronous, and may allow reading, writing, or both. Note that
+and may allow reading, writing, or both. Note that a particular type may model
-a particular type may model more than one concept. For example, the
+more than one concept. For example, the networking types  __socket__ and
-Asio types  __socket__ and __ssl_stream__ support both __SyncStream__
+__ssl_stream__ support both __SyncStream__ and __AsyncStream__. All stream
-and __AsyncStream__. All stream algorithms in Beast are declared as
+algorithms in Beast are declared as template functions using these concepts:
-template functions using these concepts:
 
 [table Stream Concepts
 [[Concept][Description]]

test/doc/core_snippets.cpp

@@ -11,6 +11,7 @@
 
 #include <boost/beast/core.hpp>
 #include <boost/asio.hpp>
+#include <boost/asio/ssl.hpp>
 #include <iostream>
 #include <thread>
 
@@ -25,13 +26,16 @@ void fxx()
 //[snippet_core_1b
 //
 using namespace boost::beast;
+namespace net = boost::asio;
+namespace ssl = boost::asio::ssl;
+using tcp = net::ip::tcp;
 
 net::io_context ioc;
 auto work = net::make_work_guard(ioc);
 std::thread t{[&](){ ioc.run(); }};
 
 error_code ec;
-net::ip::tcp::socket sock{ioc};
+tcp::socket sock{ioc};
 
 //]
     boost::ignore_unused(ec);
@@ -39,11 +43,14 @@ net::ip::tcp::socket sock{ioc};
     {
 //[snippet_core_2
 
-char const* const host = "www.example.com";
+// The resolver is used to look up IP addresses and port numbers from a domain and service name pair
-net::ip::tcp::resolver r{ioc};
+tcp::resolver r{ioc};
-net::ip::tcp::socket stream{ioc};
+
-auto const results = r.resolve(host, "http");
+// A socket represents the local end of a connection between two peers
-net::connect(stream, results.begin(), results.end());
+tcp::socket stream{ioc};
+
+// Establish a connection before sending and receiving data
+net::connect(stream, r.resolve("www.example.com", "http"));
 
 // At this point `stream` is a connected to a remote
 // host and may be used to perform stream operations.