Tidy up includes and javadocs

include/beast/http.hpp

@@ -26,6 +26,7 @@
 #include <beast/http/status.hpp>
 #include <beast/http/string_body.hpp>
 #include <beast/http/string_view_body.hpp>
+#include <beast/http/type_traits.hpp>
 #include <beast/http/verb.hpp>
 #include <beast/http/vector_body.hpp>
 #include <beast/http/write.hpp>

include/beast/http/buffer_body.hpp

@@ -19,10 +19,12 @@
 namespace beast {
 namespace http {
 
-/** A serializable body represented by caller provided buffers.
+/** A @b Body using a caller provided buffer
 
-    This body type permits the use of @ref parser or @ref serializer
+    Messages using this body type may be serialized and parsed.
-    with caller provided buffers.
+    To use this class, the caller must initialize the members
+    of @ref buffer_body::value_type to appropriate values before
+    each call to read or write during a stream operation.
 */
 struct buffer_body
 {
@@ -86,8 +88,11 @@ struct buffer_body
         bool more = true;
     };
 
+    /** The algorithm for serializing the body
+
+        Meets the requirements of @b BodyReader.
+    */
 #if BEAST_DOXYGEN
-    /// The algorithm to obtain buffers representing the body
     using reader = implementation_defined;
 #else
     class reader
@@ -146,8 +151,11 @@ struct buffer_body
     };
 #endif
 
+    /** The algorithm for parsing the body
+
+        Meets the requirements of @b BodyReader.
+    */
 #if BEAST_DOXYGEN
-    /// The algorithm used store buffers in this body
     using writer = implementation_defined;
 #else
     class writer

include/beast/http/dynamic_body.hpp

@@ -20,9 +20,11 @@
 namespace beast {
 namespace http {
 
-/** An HTTP message body represented by a @b DynamicBuffer.
+/** A @b Body using a @b DynamicBuffer
 
-    Meets the requirements of @b Body.
+    This body uses a @b DynamicBuffer as a memory-based container
+    for holding message payloads. Messages using this body type
+    may be serialized and parsed.
 */
 template<class DynamicBuffer>
 struct basic_dynamic_body
@@ -30,10 +32,19 @@ struct basic_dynamic_body
     static_assert(is_dynamic_buffer<DynamicBuffer>::value,
         "DynamicBuffer requirements not met");
 
-    /// The type of the body member when used in a message.
+    /** The type of container used for the body
+
+        This determines the type of @ref message::body
+        when this body type is used with a message container.
+    */
     using value_type = DynamicBuffer;
 
-    /// Returns the content length of this body in a message.
+    /** Returns the payload size of the body
+
+        When this body is used with @ref message::prepare_payload,
+        the Content-Length will be set to the payload size, and
+        any chunked Transfer-Encoding will be removed.
+    */
     static
     std::uint64_t
     size(value_type const& v)
@@ -41,8 +52,11 @@ struct basic_dynamic_body
         return v.size();
     }
 
+    /** The algorithm for serializing the body
+
+        Meets the requirements of @b BodyReader.
+    */
 #if BEAST_DOXYGEN
-    /// The algorithm to obtain buffers representing the body
     using reader = implementation_defined;
 #else
     class reader
@@ -76,8 +90,11 @@ struct basic_dynamic_body
     };
 #endif
 
+    /** The algorithm for parsing the body
+
+        Meets the requirements of @b BodyReader.
+    */
 #if BEAST_DOXYGEN
-    /// The algorithm used store buffers in this body
     using writer = implementation_defined;
 #else
     class writer

include/beast/http/empty_body.hpp

@@ -16,26 +16,32 @@
 namespace beast {
 namespace http {
 
-/** An empty message body.
+/** An empty @b Body
 
     This body is used to represent messages which do not have a
     message body. If this body is used with a parser, and the
     parser encounters octets corresponding to a message body,
     the parser will fail with the error @ref http::unexpected_body.
 
-    Meets the requirements of @b Body. The Content-Length of this
+    The Content-Length of this body is always 0.
-    body is always 0.
 */
 struct empty_body
 {
-    /// The type of the body member when used in a message.
+    /** The type of container used for the body
+
+        This determines the type of @ref message::body
+        when this body type is used with a message container.
+    */
     struct value_type
     {
-        // VFALCO We could stash boost::optional<std::uint64_t>
-        //        for the content length here, set on init()
     };
 
-    /// Returns the content length of the body in a message.
+    /** Returns the payload size of the body
+
+        When this body is used with @ref message::prepare_payload,
+        the Content-Length will be set to the payload size, and
+        any chunked Transfer-Encoding will be removed.
+    */
     static
     std::uint64_t
     size(value_type)
@@ -43,8 +49,11 @@ struct empty_body
         return 0;
     }
 
+    /** The algorithm for serializing the body
+
+        Meets the requirements of @b BodyReader.
+    */
 #if BEAST_DOXYGEN
-    /// The algorithm to obtain buffers representing the body
     using reader = implementation_defined;
 #else
     struct reader
@@ -74,8 +83,11 @@ struct empty_body
     };
 #endif
 
+    /** The algorithm for parsing the body
+
+        Meets the requirements of @b BodyReader.
+    */
 #if BEAST_DOXYGEN
-    /// The algorithm used store buffers in this body
     using writer = implementation_defined;
 #else
     struct writer

test/http/empty_body.cpp

@@ -7,3 +7,13 @@
 
 // Test that header file is self-contained.
 #include <beast/http/empty_body.hpp>
+
+namespace beast {
+namespace http {
+
+BOOST_STATIC_ASSERT(is_body<empty_body>::value);
+BOOST_STATIC_ASSERT(is_body_reader<empty_body>::value);
+BOOST_STATIC_ASSERT(is_body_writer<empty_body>::value);
+
+} // http
+} // beast