[FOLD]

Author: vinniefalco

doc/modules/ROOT/pages/2.messages.adoc

@@ -56,3 +56,58 @@ The following table lists the types used to model containers and views:
 
 |===
 
+== Construction
+
+All containers maintain the following invariants:
+
+* The container’s contents are always stored in serialized form that is
+  syntactically valid.
+
+* Any modification that would produce a malformed field or start line
+  throws an exception, with strong exception safety guaranteed.
+
+To satisfy these invariants, a default-constructed container provides an
+initial start line:
+
+[source,cpp]
+----
+request req;
+response res;
+
+assert(req->buffer() == "GET / HTTP/1.1\r\n\r\n");
+assert(res->buffer() == "HTTP/1.1 200 OK\r\n\r\n");
+----
+
+The `buffer` function runs in constant time, never throws exceptions,
+and returns a cpp:boost::core::string_view[] representing the complete
+serialized object.
+
+Each header field consists of a name and a value, both stored as strings,
+with prescribed ABNF format:
+
+[source]
+----
+field-name     = token
+field-value    = *( field-content / obs-fold )
+field-content  = field-vchar [ 1*( SP / HTAB ) field-vchar ]
+field-vchar    = VCHAR / obs-text
+
+obs-fold       = CRLF 1*( SP / HTAB )
+               ; obsolete line folding
+----
+
+Operations which create or modify fields throw exceptions when the name or
+value do not meet the syntactic requirements of the protocol.
+
+NOTE: Individual header fields may have their own additional syntactic
+requirements, many of which are not checked by the library. For example,
+fields whose values represent dates may have particular requirements.
+Consult the relevant specifications document to ensure program correctness.
+
+Although fields can be identified by comparing their names, the library
+provides the field enumeration, which defines a large set of constants for
+well-known field names. Internally, containers maintain a lookup table so
+that specifying fields by enumeration replaces costly string comparisons
+with efficient integer comparisons.
+
+Header fields are accessed as a bidirectional range whose value type