From fe6865700197a17fd11d02dff9411b83bab4d827 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Wed, 19 Oct 2016 18:47:03 -0400 Subject: [PATCH] Clean up message docs --- CHANGELOG.md | 6 ++ include/beast/http/message.hpp | 162 ++++++++++++++++++++++++++++++--- 2 files changed, 157 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e66e6d7fe..df167358ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +1.0.0-b18 + +* Clean up message docs + +-------------------------------------------------------------------------------- + 1.0.0-b17 * Change implicit to default value in example diff --git a/include/beast/http/message.hpp b/include/beast/http/message.hpp index 90263c64be..8d503dcf69 100644 --- a/include/beast/http/message.hpp +++ b/include/beast/http/message.hpp @@ -48,10 +48,10 @@ struct request_headers */ int version; - /// The HTTP method. + /// The Request Method. std::string method; - /// The request URI. + /// The Request URI. std::string url; /// The HTTP headers. @@ -127,10 +127,13 @@ struct response_headers */ int version; - /// The HTTP response Status-Code. + /// The Response Status-Code. int status; - /// The HTTP Reason-Phrase (obsolete). + /** The Response Reason-Phrase. + + The Reason-Phrase is obsolete as of rfc7230. + */ std::string reason; /// The HTTP headers. @@ -179,12 +182,75 @@ swap( /** A container for HTTP request or response headers. */ +#if GENERATING_DOCS +template +struct message_headers +{ + /// Indicates if the message is a request. + using is_request = + std::integral_constant; + + /// The type representing the headers. + using headers_type = Headers; + + /** The HTTP version. + + This holds both the major and minor version numbers, + using these formulas: + @code + major = version / 10; + minor = version % 10; + @endcode + */ + int version; + + /** The Request Method. + + @note This field is present only if `isRequest == true`. + */ + std::string method; + + /** The Request-URI. + + @note This field is present only if `isRequest == true`. + */ + std::string url; + + /** The Response Status-Code. + + @note This field is present only if `isRequest == false`. + */ + int status; + + /** The Response Reason-Phrase. + + The Reason-Phrase is obsolete as of rfc7230. + + @note This field is present only if `isRequest == false`. + */ + std::string reason; + + /// The HTTP headers. + Headers headers; + + /** Construct message headers. + + Any provided arguments are forwarded to the + constructor of the headers member. + */ + template + message_headers(Args&&... args); +}; + +#else template using message_headers = typename std::conditional, response_headers>::type; +#endif + /** A complete HTTP message. A message can be a request or response, depending on the `isRequest` @@ -201,8 +267,68 @@ using message_headers = @tparam Headers A type meeting the requirements of Headers. */ template -struct message : message_headers +struct message : +#if GENERATING_DOCS + implementation_defined +#else + message_headers +#endif { +#if GENERATING_DOCS + /// Indicates if the message is a request. + using is_request = + std::integral_constant; + + /// The type representing the headers. + using headers_type = Headers; + + /** The type controlling the body traits. + + The body member will be of type `body_type::value_type`. + */ + using body_type = Body; + + /** The HTTP version. + + This holds both the major and minor version numbers, + using these formulas: + @code + major = version / 10; + minor = version % 10; + @endcode + */ + int version; + + /** The Request Method. + + @note This field is present only if `isRequest == true`. + */ + std::string method; + + /** The Request-URI. + + @note This field is present only if `isRequest == true`. + */ + std::string url; + + /** The Response Status-Code. + + @note This field is present only if `isRequest == false`. + */ + int status; + + /** The Response Reason-Phrase. + + The Reason-Phrase is obsolete as of rfc7230. + + @note This field is present only if `isRequest == false`. + */ + std::string reason; + + /// The HTTP headers. + Headers headers; + +#else /// The container used to hold the request or response headers using base_type = message_headers; @@ -212,6 +338,8 @@ struct message : message_headers */ using body_type = Body; +#endif + /// A container representing the body. typename Body::value_type body; @@ -247,10 +375,16 @@ struct message : message_headers /** Construct a message. @param u An argument forwarded to the body constructor. + + @note This constructor participates in overload resolution + only if `u` is not convertible to `base_type`. */ - template::type, base_type>::value>> + template::type, base_type>::value> +#endif + > explicit message(U&& u) : body(std::forward(u)) @@ -261,10 +395,16 @@ struct message : message_headers @param u An argument forwarded to the body constructor. @param v An argument forwarded to the headers constructor. + + @note This constructor participates in overload resolution + only if `u` is not convertible to `base_type`. */ - template::type, base_type>::value>> + template::type, base_type>::value> +#endif + > message(U&& u, V&& v) : base_type(std::forward(v)) , body(std::forward(u))