Body documentation work

CHANGELOG.md

@@ -8,6 +8,7 @@ Version 50
 * Use field in basic_parser
 * Tidy up basic_fields, header, and field concepts
 * Fields concept work
+* Body documentation work
 
 API Changes:
 

doc/concept/Body.qbk

@@ -15,6 +15,9 @@ In this table:
 
 * `X` is a type meeting the requirements of [*Body].
 
+* `m` is a value of type `message<b, X, F>` where `b` is a `bool` value
+  and `F` is a type meeting the requirements of [*Fields].
+
 [table Body requirements
 [[expression] [type] [semantics, pre/post-conditions]]
 [
@@ -25,8 +28,7 @@ In this table:
         If this is not movable or not copyable, the containing message
         will be not movable or not copyable.
     ]
-]
-[
+][
     [`X::writer`]
     []
     [
@@ -36,8 +38,7 @@ In this table:
         this type to obtain buffers into which parsed body octets
         are placed.
     ]
-]
-[
+][
     [`X::reader`]
     []
     [
@@ -46,8 +47,17 @@ In this table:
         constructs an object of this type to obtain buffers representing
         the message body for serialization.
     ]
-]
-[
+][
+    [`X::size(m)`]
+    [`std::uint64_t`]
+    [
+        If present, returns the serialized size of `m.body` not including
+        any chunked transfer encoding. When this function is provided,
+        [link beast.ref.http__message.prepare `message::prepare`]
+        will automatically set the content length field based on the
+        value. Otherwise, the chunked transfer encoding will be set.
+    ]
+][
     [`is_body<X>`]
     [`std::true_type`]
     [
@@ -57,4 +67,24 @@ In this table:
 ]
 ]
 
+Exemplar:
+```
+struct body
+{
+    using value_type = implementation_defined;
+
+    /// The algorithm used for extracting buffers
+    class reader;
+
+    /// The algorithm used for inserting buffers
+    class writer;
+
+    /// Returns the body's payload size
+    template<bool isRequest, class Fields>
+    static
+    std::uint64_t
+    size(message<isRequest, empty_body, Fields> const& m);
+}
+```
+
 [endsect]

doc/concept/BodyReader.qbk

@@ -45,8 +45,7 @@ In this table:
         A type which meets the requirements of __ConstBufferSequence__.
         This is the type of buffer returned by `X::get`.
     ]
-]
-[
+][
     [`X::is_deferred`]
     []
     [
@@ -62,16 +61,14 @@ In this table:
         latency experienced by the remote host when expecting to read
         the HTTP header.
     ]
-]
-[
+][
     [`X(m);`]
     []
     [
         Constructible from `m`. The lifetime of `m` is guaranteed
         to end no earlier than after the `X` is destroyed.
     ]
-]
-[
+][
     [`a.init(ec)`]
     []
     [
@@ -79,23 +76,7 @@ In this table:
         error code in `ec`, the serialization is aborted and the error
         is propagated to the caller.
     ]
-]
-[
-    [`a.content_length()`]
-    [`std::uint64_t`]
-    [
-        If this member is present, it is called after initialization
-        and before calls to provide buffers. The serialized message will
-        have the Content-Length field set to the value returned from
-        this function. If this member is absent, the serialized message
-        body will be chunk-encoded for HTTP versions 1.1 and later, else
-        the serialized message body will be sent unmodified, with the
-        error `boost::asio::error::eof` returned to the caller, to notify
-        they should close the connection to indicate the end of the message.
-        This function must be `noexcept`.
-    ]
-]
-[
+][
     [`a.get(ec)`]
     [`R<X::const_buffers_type>`]
     [
@@ -110,8 +91,7 @@ In this table:
         or `false` if the buffer returned on this call is the last
         buffer representing the body.
     ]
-]
-[
+][
     [`is_body_reader<B>`]
     [`std::true_type`]
     [
@@ -122,9 +102,9 @@ In this table:
 ]
 
 [note
-    Definitions for required [*BodyReader] member functions should
-    be declared inline so the generated code can become part of the
-    implementation.
+    Definitions for required [*BodyReader] member functions may
+    be declared inline so the generated code can become part of
+    the implementation.
 ]
 
 Exemplar:
@@ -160,16 +140,6 @@ public:
     void
     init(error_code& ec);
 
-    /** Returns the content length.
-
-        If this member is present, the implementation will set the
-        Content-Length field accordingly. If absent, the implementation
-        will use chunk-encoding or terminate the connection to indicate
-        the end of the message.
-    */
-    std::uint64_t
-    content_length();
-
     /** Returns the next buffer in the body.
 
         @li If the return value is `boost::none` (unseated optional) and

doc/concept/BodyWriter.qbk

@@ -49,8 +49,7 @@ In the table below:
         will be called the complete header is stored in `m`, and before
         parsing body octets for messages indicating that a body is present.
     ]
-]
-[
+][
     [`a.init(length,ec)`]
     []
     [
@@ -61,8 +60,7 @@ In the table below:
         [*BodyWriter] may use this information to optimize allocation.
         If `ec` is set, the error will be propagated to the caller.
     ]
-]
-[
+][
     [`a.put(b,ec)`]
     []
     [
@@ -70,16 +68,14 @@ In the table below:
         into the body representation.
         If `ec` is set, the error will be propagated to the caller.
     ]
-]
-[
+][
     [`a.finish(ec)`]
     []
     [
         This function is called when no more body octets are remaining.
         If `ec` is set, the error will be propagated to the caller.
     ]
-]
-[
+][
     [`is_body_writer<B>`]
     [`std::true_type`]
     [
@@ -88,9 +84,11 @@ In the table below:
     ]
 ]
 ]
+
 [note
-    Definitions for required [*BodyWriter] member functions should be declared
-    inline so the generated code can become part of the implementation.
+    Definitions for required [*BodyReader] member functions may
+    be declared inline so the generated code can become part of
+    the implementation.
 ]
 
 Exemplar: