boostorg/beast
1
0
Fork 1
mirror of https://github.com/boostorg/beast.git synced 2025-07-30 04:47:29 +02:00
Code Issues Packages Projects Releases Wiki Activity

Tidy up documentation:

Browse Source 
fix #135

* Fix broken references
* Move doc debug headers to extras/
* Add rfc7230 utility classes to quick reference
This commit is contained in:
Vinnie Falco
2016-10-15 21:39:24 -04:00
parent 81cd98ece5
commit e45a6418ee
12 changed files with 109 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGELOG.md
View File

@ -8,6 +8,7 @@
* Fix Reader concept doc typo
* Add is_Reader trait
* Tidy up basic_headers for documentation
* Tidy up documentation
API Changes:

52
doc/quickref.xml
View File

@ -16,10 +16,10 @@
<colspec colname="d"/>
<thead>
<row>
<entry valign="center" namest="a" nameend="b">
<entry valign="center" namest="a" nameend="c">
<bridgehead renderas="sect2">HTTP</bridgehead>
</entry>
<entry valign="center" namest="c" nameend="d">
<entry valign="center" namest="d" nameend="d">
<bridgehead renderas="sect2">WebSocket</bridgehead>
</entry>
</row>
@ -36,6 +36,7 @@
<member><link linkend="beast.ref.http__headers">headers</link></member>
<member><link linkend="beast.ref.http__message">message</link></member>
<member><link linkend="beast.ref.http__message_headers">message_headers</link></member>
<member><link linkend="beast.ref.http__parser_v1">parser_v1</link></member>
<member><link linkend="beast.ref.http__request">request</link></member>
<member><link linkend="beast.ref.http__request_headers">request_headers</link></member>
<member><link linkend="beast.ref.http__response">response</link></member>
@ -44,20 +45,11 @@
<member><link linkend="beast.ref.http__streambuf_body">streambuf_body</link></member>
<member><link linkend="beast.ref.http__string_body">string_body</link></member>
</simplelist>
<bridgehead renderas="sect3">Options</bridgehead>
<bridgehead renderas="sect3">rfc7230</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="beast.ref.http__body_max_size">body_max_size</link></member>
<member><link linkend="beast.ref.http__headers_max_size">headers_max_size</link></member>
<member><link linkend="beast.ref.http__skip_body">skip_body</link></member>
</simplelist>
<bridgehead renderas="sect3">Type Traits</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="beast.ref.http__is_Body">is_Body</link></member>
<member><link linkend="beast.ref.http__is_Parser">is_Parser</link></member>
<member><link linkend="beast.ref.http__is_Reader">is_Reader</link></member>
<member><link linkend="beast.ref.http__is_Writer">is_Reader</link></member>
<member><link linkend="beast.ref.http__has_reader">has_reader</link></member>
<member><link linkend="beast.ref.http__has_writer">has_writer</link></member>
<member><link linkend="beast.ref.http__ext_list">ext_list</link></member>
<member><link linkend="beast.ref.http__param_list">param_list</link></member>
<member><link linkend="beast.ref.http__token_list">token_list</link></member>
</simplelist>
</entry>
<entry valign="top">
@ -75,6 +67,23 @@
<member><link linkend="beast.ref.http__swap">swap</link></member>
<member><link linkend="beast.ref.http__write">write</link></member>
</simplelist>
<bridgehead renderas="sect3">Type Traits</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="beast.ref.http__is_Body">is_Body</link></member>
<member><link linkend="beast.ref.http__is_Parser">is_Parser</link></member>
<member><link linkend="beast.ref.http__is_Reader">is_Reader</link></member>
<member><link linkend="beast.ref.http__is_Writer">is_Reader</link></member>
<member><link linkend="beast.ref.http__has_reader">has_reader</link></member>
<member><link linkend="beast.ref.http__has_writer">has_writer</link></member>
</simplelist>
</entry>
<entry valign="top">
<bridgehead renderas="sect3">Options</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="beast.ref.http__body_max_size">body_max_size</link></member>
<member><link linkend="beast.ref.http__headers_max_size">headers_max_size</link></member>
<member><link linkend="beast.ref.http__skip_body">skip_body</link></member>
</simplelist>
<bridgehead renderas="sect3">Constants</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="beast.ref.http__body_what">body_what</link></member>
@ -99,6 +108,11 @@
<member><link linkend="beast.ref.websocket__reason_string">reason_string</link></member>
<member><link linkend="beast.ref.websocket__teardown_tag">teardown_tag</link></member>
</simplelist>
<bridgehead renderas="sect3">Functions</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="beast.ref.websocket__async_teardown">async_teardown</link></member>
<member><link linkend="beast.ref.websocket__teardown">teardown</link></member>
</simplelist>
<bridgehead renderas="sect3">Options</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="beast.ref.websocket__auto_fragment">auto_fragment</link></member>
@ -110,13 +124,6 @@
<member><link linkend="beast.ref.websocket__read_message_max">read_message_max</link></member>
<member><link linkend="beast.ref.websocket__write_buffer_size">write_buffer_size</link></member>
</simplelist>
</entry>
<entry valign="top">
<bridgehead renderas="sect3">Functions</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="beast.ref.websocket__async_teardown">async_teardown</link></member>
<member><link linkend="beast.ref.websocket__teardown">teardown</link></member>
</simplelist>
<bridgehead renderas="sect3">Constants</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="beast.ref.websocket__close_code">close_code</link></member>
@ -178,7 +185,6 @@
<entry valign="top">
<bridgehead renderas="sect3">Type Traits</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="beast.ref.is_AsyncReadStream">is_AsyncReadStream</link></member>
<member><link linkend="beast.ref.is_AsyncWriteStream">is_AsyncWriteStream</link></member>
<member><link linkend="beast.ref.is_AsyncStream">is_AsyncStream</link></member>

3
doc/source.dox
View File

@ -103,11 +103,10 @@ WARN_LOGFILE =
# Configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = \
../include/beast/ \
../include/beast/core \
../include/beast/http \
../include/beast/websocket \
../include/beast/doc_debug.hpp \
../extras/beast/doc_debug.hpp \
INPUT_ENCODING = UTF-8
FILE_PATTERNS =

0
include/beast/doc_debug.hpp → extras/beast/doc_debug.hpp
View File

4
include/beast/http/basic_parser_v1.hpp
View File

@ -44,7 +44,7 @@ enum values
The default headers maximum size is 16KB (16,384 bytes).
@note Objects of this type are passed to @ref set_option.
@note Objects of this type are used with basic_parser_v1::set_option.
*/
struct headers_max_size
{
@ -67,7 +67,7 @@ struct headers_max_size
The default body maximum size for requests is 4MB (four
megabytes or 4,194,304 bytes) and unlimited for responses.
@note Objects of this type are passed to @ref set_option.
@note Objects of this type are used with basic_parser_v1::set_option.
*/
struct body_max_size
{

4
include/beast/http/concepts.hpp
View File

@ -171,7 +171,7 @@ struct is_Body : std::integral_constant<bool, ...>{};
using is_Body = detail::has_value_type<T>;
#endif
/** Determine if a @ref Body has a nested type `reader`.
/** Determine if a @b Body has a nested type `reader`.
@tparam T The type to check, which must meet the
requirements of @b Body.
@ -189,7 +189,7 @@ struct has_reader<T, beast::detail::void_t<
> > : std::true_type {};
#endif
/** Determine if a @ref Body has a nested type `writer`.
/** Determine if a @b Body has a nested type `writer`.
@tparam T The type to check, which must meet the
requirements of @b Body.

8
include/beast/http/parser_v1.hpp
View File

@ -55,7 +55,7 @@ struct parser_response
p.set_option(skip_body{true});
@endcode
@note Objects of this type are passed to @ref basic_parser_v1::set_option.
@note Objects of this type are passed to @ref parser_v1::set_option.
*/
struct skip_body
{
@ -125,6 +125,11 @@ public:
@param args A list of arguments forwarded to the message constructor.
*/
#if GENERATING_DOCS
template<class... Args>
explicit
parser_v1(Args&&... args);
#else
template<class Arg1, class... ArgN,
class = typename std::enable_if<! std::is_same<
typename std::decay<Arg1>::type, parser_v1>::value>>
@ -134,6 +139,7 @@ public:
std::forward<ArgN>(argn)...)
{
}
#endif
/// Set the expect body option.
void

46
include/beast/http/rfc7230.hpp
View File

@ -19,17 +19,22 @@ namespace http {
extension. The parameter list is a series of name/value pairs
with each pair starting with a semicolon. The value is optional.
BNF:
@code
param-list = *( OWS ";" OWS param )
param = token OWS [ "=" OWS ( token / quoted-string ) ]
@endcode
If a parsing error is encountered while iterating the string,
the behavior of the container will be as if a string containing
only characters up to but excluding the first invalid character
was used to construct the list.
@par BNF
@code
param-list = *( OWS ";" OWS param )
param = token OWS [ "=" OWS ( token / quoted-string ) ]
@endcode
To use this class, construct with the string to be parsed and
then use @ref begin and @ref end, or range-for to iterate each
item:
@par Example
@code
for(auto const& param : param_list{";level=9;no_context_takeover;bits=15"})
{
@ -96,7 +101,12 @@ public:
field value. The extension list is a comma separated list of
token parameter list pairs.
BNF:
If a parsing error is encountered while iterating the string,
the behavior of the container will be as if a string containing
only characters up to but excluding the first invalid character
was used to construct the list.
@par BNF
@code
ext-list = *( "," OWS ) ext *( OWS "," [ OWS ext ] )
ext = token param-list
@ -104,15 +114,11 @@ public:
param = token OWS [ "=" OWS ( token / quoted-string ) ]
@endcode
If a parsing error is encountered while iterating the string,
the behavior of the container will be as if a string containing
only characters up to but excluding the first invalid character
was used to construct the list.
To use this class, construct with the string to be parsed and
then use @ref begin and @end, or range-for to iterate each
then use @ref begin and @ref end, or range-for to iterate each
item:
@par Example
@code
for(auto const& ext : ext_list{"none, 7z;level=9, zip;no_context_takeover;bits=15"})
{
@ -200,20 +206,21 @@ public:
header field value. The input is a comma separated list of
tokens.
BNF:
@code
token-list = *( "," OWS ) token *( OWS "," [ OWS token ] )
@endcode
If a parsing error is encountered while iterating the string,
the behavior of the container will be as if a string containing
only characters up to but excluding the first invalid character
was used to construct the list.
@par BNF
@code
token-list = *( "," OWS ) token *( OWS "," [ OWS token ] )
@endcode
To use this class, construct with the string to be parsed and
then use @ref begin and @end, or range-for to iterate each
then use @ref begin and @ref end, or range-for to iterate each
item:
@par Example
@code
for(auto const& token : token_list{"apple, pear, banana"})
std::cout << token << "\n";
@ -274,4 +281,3 @@ public:
#include <beast/http/impl/rfc7230.ipp>
#endif

2
include/beast/websocket/error.hpp
View File

@ -13,7 +13,7 @@
namespace beast {
namespace websocket {
/// Error codes returned from @ref stream operations.
/// Error codes returned from @ref beast::websocket::stream operations.
enum class error
{
/// Both sides performed a WebSocket close

35
include/beast/websocket/option.hpp
View File

@ -30,7 +30,8 @@ namespace websocket {
The default setting is to fragment messages.
@note Objects of this type are passed to @ref stream::set_option.
@note Objects of this type are used with
@ref beast::websocket::stream::set_option.
@par Example
Setting the automatic fragmentation option:
@ -76,7 +77,8 @@ struct auto_fragment
The default setting is no decorator.
@note Objects of this type are passed to @ref stream::set_option.
@note Objects of this type are used with
@ref beast::websocket::stream::set_option.
@par Example
Setting the decorator.
@ -125,7 +127,8 @@ decorate(Decorator&& d)
The default setting is to close connections after a failed
upgrade request.
@note Objects of this type are passed to @ref stream::set_option.
@note Objects of this type are used with
@ref beast::websocket::stream::set_option.
@par Example
Setting the keep alive option.
@ -160,7 +163,8 @@ struct keep_alive
The default setting is opcode::text.
@note Objects of this type are passed to @ref stream::set_option.
@note Objects of this type are used with
@ref beast::websocket::stream::set_option.
@par Example
Setting the message type to binary.
@ -190,8 +194,10 @@ struct message_type
/** Pong callback option.
Sets the callback to be invoked whenever a pong is received
during a call to @ref read, @ref read_frame, @ref async_read,
or @ref async_read_frame.
during a call to @ref beast::websocket::stream::read,
@ref beast::websocket::stream::read_frame,
@ref beast::websocket::stream::async_read, or
@ref beast::websocket::stream::async_read_frame.
Unlike completion handlers, the callback will be invoked for
each received pong during a call to any synchronous or
@ -209,8 +215,10 @@ struct message_type
operation, the callback will be invoked using the same method as
that used to invoke the final handler.
@note To remove the pong callback, construct the option with
no parameters: `set_option(pong_callback{})`
@note Objects of this type are used with
@ref beast::websocket::stream::set_option.
To remove the pong callback, construct the option with
no parameters: `set_option(pong_callback{})`
*/
#if GENERATING_DOCS
using pong_callback = implementation_defined;
@ -240,7 +248,8 @@ struct pong_callback
The default is no buffering.
@note Objects of this type are passed to @ref stream::set_option.
@note Objects of this type are used with
@ref beast::websocket::stream::set_option.
@par Example
Setting the read buffer size.
@ -272,9 +281,10 @@ struct read_buffer_size
message size over this limit will cause a protocol failure.
The default setting is 16 megabytes. A value of zero indicates
a limit of `std::numeric_limits<std::uint64_t>::max()`.
a limit of the maximum value of a `std::uint64_t`.
@note Objects of this type are passed to @ref stream::set_option.
@note Objects of this type are used with
@ref beast::websocket::stream::set_option.
@par Example
Setting the maximum read message size.
@ -316,7 +326,8 @@ struct read_message_max
open. Undefined behavior results if the option is modified after a
successful WebSocket handshake.
@note Objects of this type are passed to @ref stream::set_option.
@note Objects of this type are used with
@ref beast::websocket::stream::set_option.
@par Example
Setting the write buffer size.

26
include/beast/websocket/stream.hpp
View File

@ -818,13 +818,13 @@ public:
@li An error occurs on the stream.
This function is implemented in terms of one or more calls to the
next layer's `write_some` functions.
This function is implemented in terms of one or more calls
to the next layer's `write_some` functions.
If the close reason specifies a close code other than
@ref close_code::none, the close frame is sent with the close
code and optional reason string. Otherwise, the close frame
is sent with no payload.
@ref beast::websocket::close_code::none, the close frame is
sent with the close code and optional reason string. Otherwise,
the close frame is sent with no payload.
Callers should not attempt to write WebSocket data after
initiating the close. Instead, callers should continue
@ -847,13 +847,13 @@ public:
@li An error occurs on the stream.
This function is implemented in terms of one or more calls to the
next layer's `write_some` functions.
This function is implemented in terms of one or more calls
to the next layer's `write_some` functions.
If the close reason specifies a close code other than
@ref close_code::none, the close frame is sent with the close
code and optional reason string. Otherwise, the close frame
is sent with no payload.
@ref beast::websocket::close_code::none, the close frame is
sent with the close code and optional reason string. Otherwise,
the close frame is sent with no payload.
Callers should not attempt to write WebSocket data after
initiating the close. Instead, callers should continue
@ -886,9 +886,9 @@ public:
@ref stream::async_close) until this operation completes.
If the close reason specifies a close code other than
@ref close_code::none, the close frame is sent with the close
code and optional reason string. Otherwise, the close frame
is sent with no payload.
@ref beast::websocket::close_code::none, the close frame is
sent with the close code and optional reason string. Otherwise,
the close frame is sent with no payload.
Callers should not attempt to write WebSocket data after
initiating the close. Instead, callers should continue

9
include/beast/websocket/teardown.hpp
View File

@ -13,13 +13,13 @@
#include <type_traits>
namespace beast {
namespace websocket {
/** Tag type used to find teardown and async_teardown overloads
/** Tag type used to find @ref beast::websocket::teardown and @ref beast::websocket::async_teardown overloads
Overloads of @ref teardown and @async_teardown for user defined
types must take a value of type @ref teardown_tag in the first
Overloads of @ref beast::websocket::teardown and
@ref beast::websocket::async_teardown for user defined types
must take a value of type @ref teardown_tag in the first
argument in order to be found by the implementation.
*/
struct teardown_tag {};
@ -178,7 +178,6 @@ async_teardown(teardown_tag,
boost::asio::ip::tcp::socket& socket, TeardownHandler&& handler);
} // websocket
} // beast
#include <beast/websocket/impl/teardown.ipp>