boostorg/beast
1
0
Fork 1
mirror of https://github.com/boostorg/beast.git synced 2026-07-07 00:40:59 +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 47105f8454
commit df8d306909
12 changed files with 109 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/beast/doc_debug.hpp
-170
View File
@@ -1,170 +0,0 @@
//
// Copyright (c) 2013-2016 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)
//
#ifndef BEAST_DOC_DEBUG_HPP
#define BEAST_DOC_DEBUG_HPP
namespace beast {
#if GENERATING_DOCS
/// doc type (documentation debug helper)
using doc_type = int;
/// doc enum (documentation debug helper)
enum doc_enum
{
/// One (documentation debug helper)
one,
/// Two (documentation debug helper)
two
};
/// doc enum class (documentation debug helper)
enum class doc_enum_class : unsigned
{
/// one (documentation debug helper)
one,
/// two (documentation debug helper)
two
};
/// doc func (documentation debug helper)
void doc_func();
/// doc class (documentation debug helper)
struct doc_class
{
/// doc class member func (documentation debug helper)
void func();
};
/// (documentation debug helper)
namespace nested {
/// doc type (documentation debug helper)
using nested_doc_type = int;
/// doc enum (documentation debug helper)
enum nested_doc_enum
{
/// One (documentation debug helper)
one,
/// Two (documentation debug helper)
two
};
/// doc enum class (documentation debug helper)
enum class nested_doc_enum_class : unsigned
{
/// one (documentation debug helper)
one,
/// two (documentation debug helper)
two
};
/// doc func (documentation debug helper)
void nested_doc_func();
/// doc class (documentation debug helper)
struct nested_doc_class
{
/// doc class member func (documentation debug helper)
void func();
};
} // nested
/** This is here to help troubleshoot doc/reference.xsl problems
Embedded references:
@li type @ref doc_type
@li enum @ref doc_enum
@li enum item @ref doc_enum::one
@li enum_class @ref doc_enum_class
@li enum_class item @ref doc_enum_class::one
@li func @ref doc_func
@li class @ref doc_class
@li class func @ref doc_class::func
@li nested type @ref nested::nested_doc_type
@li nested enum @ref nested::nested_doc_enum
@li nested enum item @ref nested::nested_doc_enum::one
@li nested enum_class @ref nested::nested_doc_enum_class
@li nested enum_class item @ref nested::nested_doc_enum_class::one
@li nested func @ref nested::nested_doc_func
@li nested class @ref nested::nested_doc_class
@li nested class func @ref nested::nested_doc_class::func
*/
void doc_debug();
namespace nested {
/** This is here to help troubleshoot doc/reference.xsl problems
Embedded references:
@li type @ref doc_type
@li enum @ref doc_enum
@li enum item @ref doc_enum::one
@li enum_class @ref doc_enum_class
@li enum_class item @ref doc_enum_class::one
@li func @ref doc_func
@li class @ref doc_class
@li class func @ref doc_class::func
@li nested type @ref nested_doc_type
@li nested enum @ref nested_doc_enum
@li nested enum item @ref nested_doc_enum::one
@li nested enum_class @ref nested_doc_enum_class
@li nested enum_class item @ref nested_doc_enum_class::one
@li nested func @ref nested_doc_func
@li nested class @ref nested_doc_class
@li nested class func @ref nested_doc_class::func
*/
void nested_doc_debug();
} // nested
#endif
} // beast
#endif
include/beast/http/basic_parser_v1.hpp
+2 -2
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
{
include/beast/http/concepts.hpp
+2 -2
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.
include/beast/http/parser_v1.hpp
+7 -1
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
include/beast/http/rfc7230.hpp
+26 -20
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
include/beast/websocket/error.hpp
+1 -1
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
include/beast/websocket/option.hpp
+23 -12
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.
include/beast/websocket/stream.hpp
+13 -13
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
include/beast/websocket/teardown.hpp
+4 -5
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>