Update documentation:

* http parse functions
* Parser concept
* More detail on concepts
* Better hyperlinking

doc/beast.qbk

@@ -191,8 +191,15 @@ supporting its development.
 [include websocket.qbk]
 
 [section:types Type Requirements]
-[include core_types.qbk]
+[include types/Body.qbk]
-[include http_types.qbk]
+[include types/BufferSequence.qbk]
+[include types/Field.qbk]
+[include types/FieldSequence.qbk]
+[include types/Parser.qbk]
+[include types/Reader.qbk]
+[include types/Streambuf.qbk]
+[include types/Streams.qbk]
+[include types/Writer.qbk]
 [endsect]
 
 [include design.qbk]

doc/quickref.xml

@@ -47,8 +47,10 @@
         <entry valign="top">
           <bridgehead renderas="sect3">Functions</bridgehead>
           <simplelist type="vert" columns="1">
+            <member><link linkend="beast.ref.http__async_parse">async_parse</link></member>
             <member><link linkend="beast.ref.http__async_read">async_read</link></member>
             <member><link linkend="beast.ref.http__async_write">async_write</link></member>
+            <member><link linkend="beast.ref.http__parse">parse</link></member>
             <member><link linkend="beast.ref.http__prepare">prepare</link></member>
             <member><link linkend="beast.ref.http__read">read</link></member>
             <member><link linkend="beast.ref.http__write">write</link></member>
@@ -62,6 +64,7 @@
             <member><link linkend="beast.types.Body">Body</link></member>
             <member><link linkend="beast.types.Field">Field</link></member>
             <member><link linkend="beast.types.FieldSequence">FieldSequence</link></member>
+            <member><link linkend="beast.types.Parser">Parser</link></member>
             <member><link linkend="beast.types.Reader">Reader</link></member>
             <member><link linkend="beast.types.Writer">Writer</link></member>
           </simplelist>
@@ -163,10 +166,10 @@
           <bridgehead renderas="sect3">Concepts</bridgehead>
           <simplelist type="vert" columns="1">
             <member><link linkend="beast.types.BufferSequence">BufferSequence</link></member>
-            <member><link linkend="beast.types.stream.AsyncStream">AsyncStream</link></member>
+            <member><link linkend="beast.types.streams.AsyncStream">AsyncStream</link></member>
-            <member><link linkend="beast.types.stream.Stream">Stream</link></member>
+            <member><link linkend="beast.types.streams.Stream">Stream</link></member>
             <member><link linkend="beast.types.Streambuf">Streambuf</link></member>
-            <member><link linkend="beast.types.stream.SyncStream">SyncStream</link></member>
+            <member><link linkend="beast.types.streams.SyncStream">SyncStream</link></member>
           </simplelist>
         </entry>
       </row>

doc/reference.xsl

@@ -1528,7 +1528,7 @@
   <xsl:text>    </xsl:text>
   <xsl:choose>
     <xsl:when test="type = 'class AsyncStream'">
-      <xsl:text>class ``[link beast.types.stream.AsyncStream [*AsyncStream]]``</xsl:text>
+      <xsl:text>class ``[link beast.types.streams.AsyncStream [*AsyncStream]]``</xsl:text>
     </xsl:when>
     <xsl:when test="type = 'class AsyncReadStream'">
       <xsl:text>class ``[@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncReadStream.html [*AsyncReadStream]]``</xsl:text>
@@ -1556,13 +1556,13 @@
       <xsl:text>class ``[@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/MutableBufferSequence.html [*MutableBufferSequence]]``</xsl:text>
     </xsl:when>
    <xsl:when test="declname = 'Stream' or type = 'class Stream'">
-      <xsl:text>class ``[link beast.types.stream.Stream [*Stream]]``</xsl:text>
+      <xsl:text>class ``[link beast.types.streams.Stream [*Stream]]``</xsl:text>
     </xsl:when>
     <xsl:when test="declname = 'Streambuf' or type = 'class Streambuf'">
       <xsl:text>class ``[link beast.types.Streambuf [*Streambuf]]``</xsl:text>
     </xsl:when>
     <xsl:when test="type = 'class SyncStream'">
-      <xsl:text>class ``[link beast.types.stream.SyncStream [*SyncStream]]``</xsl:text>
+      <xsl:text>class ``[link beast.types.streams.SyncStream [*SyncStream]]``</xsl:text>
     </xsl:when>
     <xsl:when test="declname = 'SyncReadStream' or type = 'class SyncReadStream'">
       <xsl:text>class ``[@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/SyncReadStream.html [*SyncReadStream]]``</xsl:text>

doc/types/Body.qbk

@@ -0,0 +1,50 @@
+[/
+    Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com)
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:Body Body]
+
+In this table:
+
+* `X` is a type meeting the requirements of [*`Body`].
+
+[table Body requirements
+[[operation] [type] [semantics, pre/post-conditions]]
+[
+    [`X::value_type`]
+    []
+    [
+        The type of the `message::body` member.
+        If this is not movable or not copyable, the containing message
+        will be not movable or not copyable.
+    ]
+]
+[
+    [`X:value_type{}`]
+    []
+    [`DefaultConstructible`]
+]
+[
+    [`Body::reader`]
+    []
+    [
+        If present, a type meeting the requirements of
+        [link beast.types.Reader [*`Reader`]].
+        Provides an implementation to parse the body.
+    ]
+]
+[
+    [`Body::writer`]
+    []
+    [
+        If present, a type meeting the requirements of
+        [link beast.types.Writer [*`Writer`]].
+        Provides an implementation to serialize the body.
+    ]
+]
+]
+
+[endsect]

doc/types/BufferSequence.qbk

@@ -0,0 +1,15 @@
+[/
+    Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com)
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:BufferSequence BufferSequence]
+
+A `BufferSequence` is a type meeting either of the following requirements:
+
+* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConstBufferSequence.html [*`ConstBufferSequence`]]
+* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/MutableBufferSequence.html [*`MutableBufferSequence`]]
+
+[endsect]

doc/types/Field.qbk

@@ -0,0 +1,41 @@
+[/
+    Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com)
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:Field Field]
+
+A [*`Field`] represents a single HTTP header field/value pair.
+
+In this table:
+
+* `X` denotes a type meeting the requirements of [*`Field`].
+* `a` denotes a value of type `X`.
+
+[table Field requirements
+
+[[operation][type][semantics, pre/post-conditions]]
+[
+    [`a.name()`]
+    [`boost::string_ref`]
+    [
+        This function returns a value implicitly convertible to
+        `boost::string_ref` containing the case-insensitve field
+        name, without leading or trailing white space.
+    ]
+]
+[
+    [`a.value()`]
+    [`boost::string_ref`]
+    [
+        This function returns a value implicitly convertible to
+        `boost::string_ref` containing the value for the field. The
+        value is considered canonical if there is no leading or
+        trailing whitespace.
+    ]
+]
+]
+
+[endsect]

doc/types/FieldSequence.qbk

@@ -0,0 +1,51 @@
+[/
+    Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com)
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:FieldSequence FieldSequence]
+
+A [*`FieldSequence`] is an iterable container whose value type meets
+the requirements of [link beast.types.Field [*`Field`]].
+
+In this table:
+
+* `X` denotes a type that meets the requirements of [*`FieldSequence`].
+
+* `a` is a value of type `X`.
+
+[table FieldSequence requirements
+[[operation][type][semantics, pre/post-conditions]]
+[
+    [`X::value_type`]
+    []
+    [
+        A type that meets the requirements of `Field`.
+    ]
+]
+[
+    [`X::const_iterator`]
+    []
+    [
+        A type that meets the requirements of `ForwardIterator`.
+    ]
+]
+[
+    [`a.begin()`]
+    [`X::const_iterator`]
+    [
+        Returns an iterator to the beginning of the field sequence.
+    ]
+]
+[
+    [`a.end()`]
+    [`X::const_iterator`]
+    [
+        Returns an iterator to the end of the field sequence.
+    ]
+]
+]
+
+[endsect]

doc/types/Parser.qbk

@@ -0,0 +1,58 @@
+[/
+    Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com)
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:Parser Parser]
+
+A [*`Parser`] is used to deserialize HTTP/1 messages from [link beast.types.streams streams].
+Objects of this type are used with [link beast.ref.http__parse http::parse] and
+[link beast.ref.http__async_parse http::async_parse].
+
+In this table:
+
+* `X` denotes a type meeting the requirements of [*`Parser`].
+
+* `a` denotes a value of type `X`.
+
+* `b` is a value meeting the requirements of [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConvertibleToConstBuffer.html [*`ConvertibleToConstBuffer`]].
+
+* `ec` is a value of type [link beast.ref.error_code `error_code&`].
+
+[table Parser requirements
+[[operation] [type] [semantics, pre/post-conditions]]
+[
+    [`a.complete()`]
+    [`bool`]
+    [
+        Returns `true` when a complete HTTP/1 message has been parsed.
+    ]
+]
+[
+    [`a.write(b, ec)`]
+    [`std::size_t`]
+    [
+        Parses the octets in the specified input buffer sequentially until
+        an error occurs, the end of the buffer is reached, or a complete
+        HTTP/1 message has been parsed. If an error occurs, `ec` is set
+        to the error code and parsing stops. This function returns the
+        number of bytes consumed in the input buffer.
+    ]
+]
+[
+    [`a.write_eof(ec)`]
+    [`void`]
+    [
+        Indicates to the parser that no more octets will be available.
+        Typically this function is called when the end of stream is reached.
+        For example, if a call to `boost::asio::ip::tcp::socket::read_some`
+        generates a `boost::asio::error::eof` error. Some HTTP/1 messages
+        determine the end of the message body by an end of file marker or
+        closing of the connection.
+    ]
+]
+]
+
+[endsect]

doc/types/Reader.qbk

@@ -0,0 +1,54 @@
+[/
+    Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com)
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:Reader Reader]
+
+Parser implementations will construct the corresponding `reader` object
+during the parse. This customization point allows the Body to determine
+the strategy for storing incoming message body data.
+
+In this table:
+
+* `X` denotes a type meeting the requirements of [*`Reader`].
+
+* `a` denotes a value of type `X`.
+
+* `p` is any pointer.
+
+* `n` is a value convertible to `std::size_t`.
+
+* `ec` is a value of type `error_code&`.
+
+* `m` denotes a value of type `message const&` where
+    `std::is_same<decltype(m.body), Body::value_type>:value == true`
+
+
+[table Reader requirements
+[[operation] [type] [semantics, pre/post-conditions]]
+[
+    [`X a(m);`]
+    []
+    [
+        `a` is constructible from `m`. The lifetime of `m` is
+        guaranteed to end no earlier than after `a` is destroyed.
+    ]
+]
+[
+    [`a.write(p, n, ec)`]
+    [`void`]
+    [
+        Deserializes the input sequence into the body.
+        If `ec` is set, the deserialization is aborted and the error
+        is returned to the caller.
+    ]
+]
+]
+
+[note Definitions for required `Reader` member functions should be declared
+inline so the generated code becomes part of the implementation. ]
+
+[endsect]

doc/types/Streambuf.qbk

@@ -5,54 +5,32 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-
-
-[section:BufferSequence BufferSequence]
-
-A `BufferSequence` is a type meeting either of the following requirements:
-
-* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConstBufferSequence.html [*`ConstBufferSequence`]]
-* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/MutableBufferSequence.html [*`MutableBufferSequence`]]
-
-[endsect]
-
-
-
-[section:stream Streams]
-
-Stream types represent objects capable of performing synchronous or
-asynchronous I/O. They are based on concepts from `boost::asio`.
-
-[heading:Stream Stream]
-
-A type modeling [*`Stream`] meets either or both of the following requirements:
-
-* [link beast.types.stream.AsyncStream [*`AsyncStream`]]
-* [link beast.types.stream.SyncStream [*`SyncStream`]]
-
-[heading:AsyncStream AsyncStream]
-
-A type modeling [*`AsyncStream`] meets the following requirements:
-
-* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncReadStream.html [*`AsyncReadStream`]]
-* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncWriteStream.html [*`AsyncWriteStream`]]
-
-[heading:SyncStream SyncStream]
-
-A type modeling [*`SyncStream`] meets the following requirements:
-
-* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/SyncReadStream.html [*`SyncReadStream`]]
-* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/SyncWriteStream.html [*`SyncWriteStream`]]
-
-[endsect]
-
-
-
 [section:Streambuf Streambuf]
 
+A [*`Streambuf`] represents a logical octet sequence divided in two sections,
+the input sequence and the output sequence. Octets are written to the output
+sequence, then moved to the input sequence where they are available for
+reading. When some or all of the input sequence is no longer needed, it may
+be consumed.
+
+The interface to this concept is intended to permit the following
+implementation strategies:
+
+* A single contiguous octet array, which is reallocated as necessary to
+  accommodate changes in the size of the octet sequence.
+
+* A sequence of one or more octet arrays, where each array is of the same
+  size. Additional octet array objects are appended to the sequence to
+  accommodate changes in the size of the octet sequence.
+
+* A sequence of one or more octet arrays of varying sizes. Additional octet
+  array objects are appended to the sequence to accommodate changes in the
+  size of the character sequence. This is the implementation approached
+  currently offered by [link beast.ref.basic_streambuf `basic_streambuf`].
+
 In the table below:
 
-* `X` denotes a class
+* `X` denotes a class meeting the requirements of [*`Streambuf`]
 * `a` denotes a value of type `X`
 * `n` denotes a value convertible to `std::size_t`
 * `U`, `T` denote unspecified types.
@@ -62,12 +40,12 @@ In the table below:
 [
     [`X::const_buffers_type`]
     [`T`]
-    [`T` meets the requirements for `ConstBufferSequence`.]
+    [`T` meets the requirements for [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConstBufferSequence.html `ConstBufferSequence`].]
 ]
 [
     [`X::mutable_buffers_type`]
     [`U`]
-    [`U` meets the requirements for `MutableBufferSequence`.]
+    [`U` meets the requirements for [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/MutableBufferSequence.html `MutableBufferSequence`].]
 ]
 [
     [`a.commit(n)`]
@@ -98,7 +76,7 @@ In the table below:
 [
     [`a.max_size()`]
     [`std::size_t`]
-    [Returns the maximum size of the `Streambuf`.]
+    [Returns the maximum size of the stream buffer.]
 ]
 [
     [`read_size_helper(a, n)`]

doc/types/Streams.qbk

@@ -0,0 +1,34 @@
+[/
+    Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com)
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:streams Streams]
+
+Stream types represent objects capable of performing synchronous or
+asynchronous I/O. They are based on concepts from `boost::asio`.
+
+[heading:Stream Stream]
+
+A type modeling [*`Stream`] meets either or both of the following requirements:
+
+* [link beast.types.streams.AsyncStream [*`AsyncStream`]]
+* [link beast.types.streams.SyncStream [*`SyncStream`]]
+
+[heading:AsyncStream AsyncStream]
+
+A type modeling [*`AsyncStream`] meets the following requirements:
+
+* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncReadStream.html [*`AsyncReadStream`]]
+* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncWriteStream.html [*`AsyncWriteStream`]]
+
+[heading:SyncStream SyncStream]
+
+A type modeling [*`SyncStream`] meets the following requirements:
+
+* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/SyncReadStream.html [*`SyncReadStream`]]
+* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/SyncWriteStream.html [*`SyncWriteStream`]]
+
+[endsect]

doc/types/Writer.qbk

@@ -5,199 +5,6 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-
-
-[section:Body Body]
-
-In this table:
-
-* `X` is a type meeting the requirements of [*`Body`].
-
-[table Body requirements
-[[operation] [type] [semantics, pre/post-conditions]]
-[
-    [`X::value_type`]
-    []
-    [
-        The type of the `message::body` member.
-        If this is not movable or not copyable, the containing message
-        will be not movable or not copyable.
-    ]
-]
-[
-    [`X:value_type{}`]
-    []
-    [`DefaultConstructible`]
-]
-[
-    [`Body::reader`]
-    []
-    [
-        If present, a type meeting the requirements of
-        [link beast.types.Reader [*`Reader`]].
-        Provides an implementation to parse the body.
-    ]
-]
-[
-    [`Body::writer`]
-    []
-    [
-        If present, a type meeting the requirements of
-        [link beast.types.Writer [*`Writer`]].
-        Provides an implementation to serialize the body.
-    ]
-]
-]
-
-[endsect]
-
-
-
-[section:BufferSequence BufferSequence]
-
-A `BufferSequence` is a type meeting either of the following requirements:
-
-* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConstBufferSequence.html [*`ConstBufferSequence`]]
-* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/MutableBufferSequence.html [*`MutableBufferSequence`]]
-
-[endsect]
-
-
-
-[section:Field Field]
-
-A [*`Field`] represents a single HTTP header field/value pair.
-
-In this table:
-
-* `X` denotes a type meeting the requirements of [*`Field`].
-* `a` denotes a value of type `X`.
-
-[table Field requirements
-
-[[operation][type][semantics, pre/post-conditions]]
-[
-    [`a.name()`]
-    [`boost::string_ref`]
-    [
-        This function returns a value implicitly convertible to
-        `boost::string_ref` containing the case-insensitve field
-        name, without leading or trailing white space.
-    ]
-]
-[
-    [`a.value()`]
-    [`boost::string_ref`]
-    [
-        This function returns a value implicitly convertible to
-        `boost::string_ref` containing the value for the field. The
-        value is considered canonical if there is no leading or
-        trailing whitespace.
-    ]
-]
-]
-
-[endsect]
-
-
-
-[section:FieldSequence FieldSequence]
-
-A [*`FieldSequence`] is an iterable container whose value type meets
-the requirements of [link beast.types.Field [*`Field`]].
-
-In this table:
-
-* `X` denotes a type that meets the requirements of [*`FieldSequence`].
-
-* `a` is a value of type `X`.
-
-[table FieldSequence requirements
-[[operation][type][semantics, pre/post-conditions]]
-[
-    [`X::value_type`]
-    []
-    [
-        A type that meets the requirements of `Field`.
-    ]
-]
-[
-    [`X::const_iterator`]
-    []
-    [
-        A type that meets the requirements of `ForwardIterator`.
-    ]
-]
-[
-    [`a.begin()`]
-    [`X::const_iterator`]
-    [
-        Returns an iterator to the beginning of the field sequence.
-    ]
-]
-[
-    [`a.end()`]
-    [`X::const_iterator`]
-    [
-        Returns an iterator to the end of the field sequence.
-    ]
-]
-]
-
-[endsect]
-
-
-
-[section:Reader Reader]
-
-Parser implementations will construct the corresponding `reader` object
-during the parse. This customization point allows the Body to determine
-the strategy for storing incoming message body data.
-
-In this table:
-
-* `X` denotes a type meeting the requirements of [*`Reader`].
-
-* `a` denotes a value of type `X`.
-
-* `p` is any pointer.
-
-* `n` is a value convertible to `std::size_t`.
-
-* `ec` is a value of type `error_code&`.
-
-* `m` denotes a value of type `message const&` where
-    `std::is_same<decltype(m.body), Body::value_type>:value == true`
-
-
-[table Reader requirements
-[[operation] [type] [semantics, pre/post-conditions]]
-[
-    [`X a(m);`]
-    []
-    [
-        `a` is constructible from `m`. The lifetime of `m` is
-        guaranteed to end no earlier than after `a` is destroyed.
-    ]
-]
-[
-    [`a.write(p, n, ec)`]
-    [`void`]
-    [
-        Deserializes the input sequence into the body.
-        If `ec` is set, the deserialization is aborted and the error
-        is returned to the caller.
-    ]
-]
-]
-
-[note Definitions for required `Reader` member functions should be declared
-inline so the generated code becomes part of the implementation. ]
-
-[endsect]
-
-
-
 [section:Writer Writer]
 
 A `Writer` serializes the message body. The implementation creates an instance
@@ -370,4 +177,3 @@ public:
 ```
 
 [endsect]
-