Documentation work

include/beast/http/fields.hpp

@@ -26,7 +26,7 @@ namespace http {
 /** A container for storing HTTP header fields.
 
     This container is designed to store the field value pairs that make
-    up the fields and trailers in a HTTP message. Objects of this type
+    up the fields and trailers in an HTTP message. Objects of this type
     are iterable, with each element holding the field name and field
     value.
 

include/beast/http/message.hpp

@@ -20,7 +20,7 @@
 namespace beast {
 namespace http {
 
-/** A container for a HTTP request or response header.
+/** A container for an HTTP request or response header.
 
     A header includes the Start Line and Fields.
 
@@ -160,7 +160,7 @@ struct header<true, Fields>
     }
 };
 
-/** A container for a HTTP request or response header.
+/** A container for an HTTP request or response header.
 
     A header includes the Start Line and Fields.
 
@@ -510,7 +510,7 @@ enum class connection
     upgrade
 };
 
-/** Prepare a HTTP message.
+/** Prepare an HTTP message.
 
     This function will adjust the Content-Length, Transfer-Encoding,
     and Connection fields of the message based on the properties of

include/beast/http/read.hpp

@@ -208,7 +208,7 @@ async_read_some(
 
 //------------------------------------------------------------------------------
 
-/** Read an HTTP/1 message from a stream.
+/** Read into an HTTP/1 parser from a stream.
 
     This function synchronously reads from a stream and passes
     data to the specified parser. The call will block until one
@@ -252,7 +252,7 @@ read(
     DynamicBuffer& buffer,
     basic_parser<isRequest, isDirect, Derived>& parser);
 
-/** Read an HTTP/1 message from a stream.
+/** Read into an HTTP/1 parser from a stream.
 
     This function synchronously reads from a stream and passes
     data to the specified parser. The call will block until one
@@ -297,7 +297,7 @@ read(
     basic_parser<isRequest, isDirect, Derived>& parser,
     error_code& ec);
 
-/** Start an asynchronous operation to read an HTTP/1 message from a stream.
+/** Read into an HTTP/1 parser asynchronously from a stream.
 
     This function is used to asynchronously read from a stream and
     pass the data to the specified parser. The function call always
@@ -406,7 +406,7 @@ read(
     DynamicBuffer& buffer,
     message<isRequest, Body, Fields>& msg);
 
-/** Read a HTTP/1 message from a stream.
+/** Read an HTTP/1 message from a stream.
 
     This function is used to synchronously read a message from
     a stream. The call blocks until one of the following conditions
@@ -453,7 +453,7 @@ read(
     message<isRequest, Body, Fields>& msg,
     error_code& ec);
 
-/** Read a HTTP/1 message asynchronously from a stream.
+/** Read an HTTP/1 message asynchronously from a stream.
 
     This function is used to asynchronously read a message from
     a stream. The function call always returns immediately. The

include/beast/http/rfc7230.hpp

@@ -15,9 +15,9 @@
 namespace beast {
 namespace http {
 
-/** A list of parameters in a HTTP extension field value.
+/** A list of parameters in an HTTP extension field value.
 
-    This container allows iteration of the parameter list in a HTTP
+    This container allows iteration of the parameter list in an HTTP
     extension. The parameter list is a series of name/value pairs
     with each pair starting with a semicolon. The value is optional.
 
@@ -99,7 +99,7 @@ public:
 
 /** A list of extensions in a comma separated HTTP field value.
 
-    This container allows iteration of the extensions in a HTTP
+    This container allows iteration of the extensions in an HTTP
     field value. The extension list is a comma separated list of
     token parameter list pairs.
 

include/beast/http/serializer.hpp

@@ -201,8 +201,8 @@ class serializer
 public:
     /** Constructor
 
-        @param msg The message to serialize. The message object
-        must remain valid for the lifetime of the write stream.
+        @param msg The message to serialize, which must
+        remain valid for the lifetime of the serializer.
 
         @param decorator An optional decorator to use.
 
@@ -213,7 +213,7 @@ public:
         Decorator const& decorator = Decorator{},
             Allocator const& alloc = Allocator{});
 
-    /** Returns `true` if we will pause after writing the header.
+    /** Returns `true` if we will pause after writing the complete header.
     */
     bool
     split() const
@@ -227,8 +227,8 @@ public:
         write only the octets corresponding to the serialized header
         first. If the header has already been written, this function
         will have no effect on output. This function should be called
-        before any writes take place, otherwise the behavior is
-        undefined.
+        before retrieving any buffers using @ref get, otherwise the
+        behavior is undefined.
     */
     void
     split(bool v)
@@ -238,9 +238,8 @@ public:
 
     /** Return `true` if serialization of the header is complete.
 
-        This function indicates whether or not all octets
-        corresponding to the serialized representation of the
-        header have been successfully delivered to the stream.
+        This function indicates whether or not all buffers containing
+        serialized header octets have been retrieved.
     */
     bool
     is_header_done() const
@@ -248,11 +247,11 @@ public:
         return header_done_;
     }
 
-    /** Return `true` if serialization is complete
+    /** Return `true` if serialization is complete.
 
         The operation is complete when all octets corresponding
         to the serialized representation of the message have been
-        successfully delivered to the stream.
+        successfully retrieved.
     */
     bool
     is_done() const
@@ -262,9 +261,11 @@ public:
 
     /** Return `true` if Connection: close semantic is indicated.
 
-        After serialization is complete, if there is an
-        underlying network connection then it should be closed if
-        this function returns `true`.
+        Depending on the contents of the message, the end of
+        the body may be indicated by the end of file. In order
+        for the recipient (if any) to receive a complete message,
+        the underlying network connection must be closed when this
+        function returns `true`.
     */
     bool
     needs_close() const
@@ -288,7 +289,8 @@ public:
 
         @param visit The function to call. The equivalent function
         signature of this object must be:
-        @code template<class ConstBufferSequence>
+        @code
+            template<class ConstBufferSequence>
             void visit(error_code&, ConstBufferSequence const&);
         @endcode
         The function is not copied, if no error occurs it will be

include/beast/http/write.hpp

@@ -132,7 +132,7 @@ async_write_some(AsyncWriteStream& stream, serializer<
     isRequest, Body, Fields, Decorator, Allocator>& sr,
         WriteHandler&& handler);
 
-/** Write a HTTP/1 message to a stream.
+/** Write an HTTP/1 message to a stream.
 
     This function is used to write a message to a stream. The call
     will block until one of the following conditions is true:
@@ -163,7 +163,7 @@ void
 write(SyncWriteStream& stream,
     message<isRequest, Body, Fields> const& msg);
 
-/** Write a HTTP/1 message on a stream.
+/** Write an HTTP/1 message to a stream.
 
     This function is used to write a message to a stream. The call
     will block until one of the following conditions is true:
@@ -195,7 +195,7 @@ write(SyncWriteStream& stream,
     message<isRequest, Body, Fields> const& msg,
         error_code& ec);
 
-/** Write a HTTP/1 message asynchronously to a stream.
+/** Write an HTTP/1 message asynchronously to a stream.
 
     This function is used to asynchronously write a message to
     a stream. The function call always returns immediately. The
@@ -247,7 +247,7 @@ async_write(AsyncWriteStream& stream,
 
 //------------------------------------------------------------------------------
 
-/** Serialize a HTTP/1 header to a `std::ostream`.
+/** Serialize an HTTP/1 header to a `std::ostream`.
 
     The function converts the header to its HTTP/1 serialized
     representation and stores the result in the output stream.
@@ -261,7 +261,7 @@ std::ostream&
 operator<<(std::ostream& os,
     header<isRequest, Fields> const& msg);
 
-/** Serialize a HTTP/1 message to a `std::ostream`.
+/** Serialize an HTTP/1 message to a `std::ostream`.
 
     The function converts the message to its HTTP/1 serialized
     representation and stores the result in the output stream.