From 4a4d535d98d0e859be37a150546841c4ede05a43 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Fri, 15 Dec 2017 09:00:44 -0800 Subject: [PATCH] Documentation --- CHANGELOG.md | 1 + doc/qbk/00_main.qbk | 2 +- doc/qbk/01_intro.qbk | 32 +++++++++++++++++++++++-- doc/qbk/02_examples.qbk | 6 +++-- doc/qbk/03_core/5_composed.qbk | 2 +- doc/qbk/08_design.qbk | 2 +- doc/qbk/08_design/2_http_comparison.qbk | 4 ++-- 7 files changed, 40 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b2a3ed0..975bbc87 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ Version 150: * handler_ptr tests +* Documentation API Changes: diff --git a/doc/qbk/00_main.qbk b/doc/qbk/00_main.qbk index 777c6bfc..5685cc56 100644 --- a/doc/qbk/00_main.qbk +++ b/doc/qbk/00_main.qbk @@ -30,7 +30,7 @@ [template include_file[path][^<''''''[path]''''''>]] [def __N3747__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf [*N3747]]] -[def __N4588__ [@http://cplusplus.github.io/networking-ts/draft.pdf [*N4588]]] +[def __NetTS__ [@http://cplusplus.github.io/networking-ts/draft.pdf [*Networking.TS]]] [def __rfc6455__ [@https://tools.ietf.org/html/rfc6455 rfc6455]] [def __rfc7230__ [@https://tools.ietf.org/html/rfc7230 rfc7230]] diff --git a/doc/qbk/01_intro.qbk b/doc/qbk/01_intro.qbk index d06643a4..5a9771cb 100644 --- a/doc/qbk/01_intro.qbk +++ b/doc/qbk/01_intro.qbk @@ -8,6 +8,7 @@ ] [section Introduction] +[block''''''] Beast is a C++ header-only library serving as a foundation for writing interoperable networking libraries by providing [*low-level HTTP/1, @@ -43,7 +44,9 @@ to enable client side programs (often written in JavaScript) to communicate interactively. C++ benefits greatly from having a standardized implementation of these protocols. -[heading Requirements] + + +[section Requirements] [important This library is for programmers familiar with __Asio__. Users who @@ -68,6 +71,23 @@ library. Please visit the [@boost:/more/getting_started.html Boost documentation] for instructions on how to do this for your particular build system. +[endsect] + + + +[section Reporting Bugs] + +To report bugs or get help using Beast, GitHub issues are preferred. +Please visit +[@https://github.com/boostorg/beast/issues https://github.com/boostorg/beast/issues] +to ask a question, report a defect, or request a feature. If you +prefer to keep your issue or question confidential please email the author at +[@mailto:vinnie.falco%40gmail.com vinnie.falco@gmail.com]. + +[endsect] + + + [heading Credits] Boost.Asio is the inspiration behind which all of the interfaces and @@ -75,7 +95,9 @@ implementation strategies are built. Some parts of the documentation are written to closely resemble the wording and presentation of Boost.Asio documentation. Credit goes to [@https://github.com/chriskohlhoff Christopher Kohlhoff] -for his wonderful Asio library and the ideas in __N4588__ which power Beast. +for his wonderful Asio library and the ideas in +[@http://cplusplus.github.io/networking-ts/draft.pdf [*C++ Extensions for Networking]] +which power Beast. Beast would not be possible without the support of [@https://www.ripple.com Ripple] @@ -96,8 +118,14 @@ and for tirelessly answering questions on [@https://cpplang.slack.com/ Cpplang-Slack]. +Thanks to +[@https://github.com/djarek Damian Jarek] +for his generous participation and source code contributions. + [endsect] + + [section Reports] [block''''''] diff --git a/doc/qbk/02_examples.qbk b/doc/qbk/02_examples.qbk index 673f6c34..16196f59 100644 --- a/doc/qbk/02_examples.qbk +++ b/doc/qbk/02_examples.qbk @@ -179,7 +179,8 @@ and illustrate the implementation of advanced features. [[itemized_list [HTTP pipelining] [Asynchronous timeouts] - [Dual protocols: HTTP and WebSocket]]] + [Dual protocols: HTTP and WebSocket] + [WebSocket use idle ping for timeout]]] [[example_src example/advanced/server/advanced_server.cpp advanced_server.cpp]] ][ [Advanced, flex (plain + SSL)] @@ -187,7 +188,8 @@ and illustrate the implementation of advanced features. [HTTP pipelining] [Asynchronous timeouts] [Dual protocols: HTTP and WebSocket] - [Flexible ports; plain and SSL on the same port]]] + [WebSocket use idle ping for timeout] + [Flexible ports: plain and SSL on the same port]]] [[example_src example/advanced/server-flex/advanced_server_flex.cpp advanced_server_flex.cpp]] ]] diff --git a/doc/qbk/03_core/5_composed.qbk b/doc/qbk/03_core/5_composed.qbk index ca645dbe..8c988120 100644 --- a/doc/qbk/03_core/5_composed.qbk +++ b/doc/qbk/03_core/5_composed.qbk @@ -19,7 +19,7 @@ special tokens __use_future__ and __yield_context__ for using futures and coroutines respectively. This system of customizing the return value and method of completion notification is known as the ['Extensible Asynchronous Model] described in __N3747__, and a built in -to __N4588__. Here is an example of an initiating function which reads a +to __NetTS__. Here is an example of an initiating function which reads a line from the stream and echoes it back. This function is developed further in the next section: diff --git a/doc/qbk/08_design.qbk b/doc/qbk/08_design.qbk index 04704181..c1e15e4b 100644 --- a/doc/qbk/08_design.qbk +++ b/doc/qbk/08_design.qbk @@ -27,7 +27,7 @@ flaws exhibited by other libraries: managing flow control, to the user. Beast uses the __DynamicBuffer__ concept presented in the Networking TS -(__N4588__), and relies heavily on the __ConstBufferSequence__ and +(__NetTS__), and relies heavily on the __ConstBufferSequence__ and __MutableBufferSequence__ concepts for passing buffers to functions. The authors have found the dynamic buffer and buffer sequence interfaces to be optimal for interacting with Asio, and for other tasks such as incremental diff --git a/doc/qbk/08_design/2_http_comparison.qbk b/doc/qbk/08_design/2_http_comparison.qbk index 01f1115f..adb859fa 100644 --- a/doc/qbk/08_design/2_http_comparison.qbk +++ b/doc/qbk/08_design/2_http_comparison.qbk @@ -107,7 +107,7 @@ holds the header fields. We note some problems with the container declaration: range destroys information conveyed by the __ConstBufferSequence__ and __MutableBufferSequence__ used in dynamic buffers. The consequence is that cpp-netlib implementations will be less efficient than an - equivalent __N4588__ conforming implementation. + equivalent __NetTS__ conforming implementation. * The library uses specializations of `string` to change the type of string used everywhere, including the body, field name and value @@ -217,7 +217,7 @@ struct is_message>: public std::true_type {}; destroys information conveyed by the __ConstBufferSequence__ and __MutableBufferSequence__ used in dynamic buffers. The consequence is that Boost.HTTP implementations will be less efficient when dealing - with body containers than an equivalent __N4588__ conforming + with body containers than an equivalent __NetTS__ conforming implementation. * The [*Body] customization point constrains user defined types to