diff --git a/CHANGELOG.md b/CHANGELOG.md index 6004df27..7bd7797a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ * Fix Reader concept doc typo * Add is_Reader trait * Tidy up basic_headers for documentation +* Tidy up documentation API Changes: diff --git a/doc/quickref.xml b/doc/quickref.xml index 4182c96e..20feb6ab 100644 --- a/doc/quickref.xml +++ b/doc/quickref.xml @@ -16,10 +16,10 @@ - + HTTP - + WebSocket @@ -36,6 +36,7 @@ headers message message_headers + parser_v1 request request_headers response @@ -44,20 +45,11 @@ streambuf_body string_body - Options + rfc7230 - body_max_size - headers_max_size - skip_body - - Type Traits - - is_Body - is_Parser - is_Reader - is_Reader - has_reader - has_writer + ext_list + param_list + token_list @@ -75,6 +67,23 @@ swap write + Type Traits + + is_Body + is_Parser + is_Reader + is_Reader + has_reader + has_writer + + + + Options + + body_max_size + headers_max_size + skip_body + Constants body_what @@ -99,6 +108,11 @@ reason_string teardown_tag + Functions + + async_teardown + teardown + Options auto_fragment @@ -110,13 +124,6 @@ read_message_max write_buffer_size - - - Functions - - async_teardown - teardown - Constants close_code @@ -178,7 +185,6 @@ Type Traits - is_AsyncReadStream is_AsyncWriteStream is_AsyncStream diff --git a/doc/source.dox b/doc/source.dox index 240c61de..25396540 100644 --- a/doc/source.dox +++ b/doc/source.dox @@ -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 = diff --git a/include/beast/doc_debug.hpp b/extras/beast/doc_debug.hpp similarity index 100% rename from include/beast/doc_debug.hpp rename to extras/beast/doc_debug.hpp diff --git a/include/beast/http/basic_parser_v1.hpp b/include/beast/http/basic_parser_v1.hpp index 86a13e1d..78654a36 100644 --- a/include/beast/http/basic_parser_v1.hpp +++ b/include/beast/http/basic_parser_v1.hpp @@ -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 { diff --git a/include/beast/http/concepts.hpp b/include/beast/http/concepts.hpp index d490196d..f77777de 100644 --- a/include/beast/http/concepts.hpp +++ b/include/beast/http/concepts.hpp @@ -171,7 +171,7 @@ struct is_Body : std::integral_constant{}; using is_Body = detail::has_value_type; #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 > : 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. diff --git a/include/beast/http/parser_v1.hpp b/include/beast/http/parser_v1.hpp index 692e6c06..b4abf957 100644 --- a/include/beast/http/parser_v1.hpp +++ b/include/beast/http/parser_v1.hpp @@ -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 + explicit + parser_v1(Args&&... args); +#else template::type, parser_v1>::value>> @@ -134,6 +139,7 @@ public: std::forward(argn)...) { } +#endif /// Set the expect body option. void diff --git a/include/beast/http/rfc7230.hpp b/include/beast/http/rfc7230.hpp index c6bd24dc..15407d0f 100644 --- a/include/beast/http/rfc7230.hpp +++ b/include/beast/http/rfc7230.hpp @@ -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 #endif - diff --git a/include/beast/websocket/error.hpp b/include/beast/websocket/error.hpp index e259fee0..12e1306d 100644 --- a/include/beast/websocket/error.hpp +++ b/include/beast/websocket/error.hpp @@ -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 diff --git a/include/beast/websocket/option.hpp b/include/beast/websocket/option.hpp index 71355676..818a74f3 100644 --- a/include/beast/websocket/option.hpp +++ b/include/beast/websocket/option.hpp @@ -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::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. diff --git a/include/beast/websocket/stream.hpp b/include/beast/websocket/stream.hpp index 71ef23a9..ee46911c 100644 --- a/include/beast/websocket/stream.hpp +++ b/include/beast/websocket/stream.hpp @@ -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 diff --git a/include/beast/websocket/teardown.hpp b/include/beast/websocket/teardown.hpp index d3ffd2c8..3682a18f 100644 --- a/include/beast/websocket/teardown.hpp +++ b/include/beast/websocket/teardown.hpp @@ -13,13 +13,13 @@ #include 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