From e389b853c56ffb2991d4631dce66ecff23258caf Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Fri, 23 Jun 2017 10:52:10 -0700 Subject: [PATCH] Documentation work --- doc/5_02_message.qbk | 110 +++++++++++++++++++------------- doc/5_04_serializer_streams.qbk | 46 ++++++++++++- doc/5_05_parser_streams.qbk | 2 +- doc/concept/Body.qbk | 9 +++ doc/concept/DynamicBuffer.qbk | 10 +++ doc/concept/Fields.qbk | 5 ++ test/http/doc_snippets.cpp | 36 ----------- 7 files changed, 133 insertions(+), 85 deletions(-) diff --git a/doc/5_02_message.qbk b/doc/5_02_message.qbk index b59924f4..1a7c6992 100644 --- a/doc/5_02_message.qbk +++ b/doc/5_02_message.qbk @@ -11,22 +11,40 @@ Beast provides a single class template __message__ and some aliases which model HTTP/1 and [@https://tools.ietf.org/html/rfc7540 HTTP/2] messages: -``` -/// An HTTP message -template< - bool isRequest, // `true` for requests, `false` for responses - class Body, // Controls the container and algorithms used for the body - class Fields = fields> // The type of container to store the fields -class message; -/// A typical HTTP request -template -using request = message; - -/// A typical HTTP response -template -using response = message; -``` +[table Message +[[Name][Description]] +[[ + __message__ +][ + ``` + /// An HTTP message + template< + bool isRequest, // `true` for requests, `false` for responses + class Body, // Controls the container and algorithms used for the body + class Fields = fields> // The type of container to store the fields + class message; + ``` +]] +[[ + [link beast.ref.beast__http__request `request`] +][ + ``` + /// A typical HTTP request + template + using request = message; + ``` +]] +[[ + [link beast.ref.beast__http__response `response`] +][ + ``` + /// A typical HTTP response + template + using response = message; + ``` +]] +] The container offers value semantics including move and copy if supported by __Body__ and __Fields__. User defined template function parameters can @@ -42,21 +60,39 @@ As with fields, user defined body types are possible. Sometimes it is desired to only work with a header. Beast provides a single class template __header__ and some aliases to model HTTP/1 and HTTP/2 headers: -``` -/// An HTTP header -template< - bool isRequest, // `true` for requests, `false` for responses - class Fields = fields> // The type of container to store the fields -class header; -/// A typical HTTP request header -template -using request_header = header; - -/// A typical HTTP response header -template -using response_header = header; -``` +[table Header +[[Name][Description]] +[[ + __header__ +][ + ``` + /// An HTTP header + template< + bool isRequest, // `true` for requests, `false` for responses + class Fields = fields> // The type of container to store the fields + class header; + ``` +]] +[[ + [link beast.ref.beast__http__request_header `request_header`] +][ + ``` + /// A typical HTTP request header + template + using request_header = header; + ``` +]] +[[ + [link beast.ref.beast__http__response_header `response_header`] +][ + ``` + /// A typical HTTP response header + template + using response_header = header; + ``` +]] +] Requests and responses share the version, fields, and body but have a few members unique to the type. This is implemented by declaring the @@ -70,22 +106,6 @@ notable differences in members in each partial specialization: [$images/message.png [width 730px] [height 410px]] -The template type aliases -[link beast.ref.beast__http__request `request`] and -[link beast.ref.beast__http__response `response`] -are provided for brevity. They specify __fields__ as the default for [*Fields]. - - -``` -/// A typical HTTP request -template -using request = message; - -/// A typical HTTP response -template -using response = message; -``` - [heading:body Body Types] Beast defines the __Body__ concept, which determines both the type of diff --git a/doc/5_04_serializer_streams.qbk b/doc/5_04_serializer_streams.qbk index 5a9c3431..62a556ac 100644 --- a/doc/5_04_serializer_streams.qbk +++ b/doc/5_04_serializer_streams.qbk @@ -19,10 +19,50 @@ at once, such as: * Use a series of caller-provided buffers to represent the body. These tasks may be performed by using the serializer stream interfaces. -To use these interfaces, first construct a __serializer__ object with -the message to be sent. The serializer type has these declarations: +To use these interfaces, first construct a suitable object with +the message to be sent: -[http_snippet_9] +[table Serializer +[[Name][Description]] +[[ + __serializer__ +][ + ``` + /// Provides buffer oriented HTTP message serialization functionality. + template< + bool isRequest, + class Body, + class Fields = fields, + class ChunkDecorator = no_chunk_decorator + > + class serializer; + ``` +]] +[[ + [link beast.ref.beast__http__request_serializer `request_serializer`] +][ + ``` + /// A serializer for HTTP/1 requests + template< + class Body, + class Fields = fields, + class ChunkDecorator = no_chunk_decorator> + using request_serializer = serializer; + ``` +]] +[[ + [link beast.ref.beast__http__response_serializer `response_serializer`] +][ + ``` + /// A serializer for HTTP/1 responses + template< + class Body, + class Fields = fields, + class ChunkDecorator = no_chunk_decorator> + using response_serializer = serializer; + ``` +]] +] The choices for template types must match the message passed on construction. This code creates an HTTP response and the corresponding serializer: diff --git a/doc/5_05_parser_streams.qbk b/doc/5_05_parser_streams.qbk index f3edfa3a..2f481eb0 100644 --- a/doc/5_05_parser_streams.qbk +++ b/doc/5_05_parser_streams.qbk @@ -24,7 +24,7 @@ associated state, by constructing a class derived from __basic_parser__. Beast comes with the derived instance __parser__ which creates complete __message__ objects; user-defined parsers are also possible: -[table Parser Implementations +[table Parser [[Name][Description]] [[ __parser__ diff --git a/doc/concept/Body.qbk b/doc/concept/Body.qbk index 12109b69..87dd05c0 100644 --- a/doc/concept/Body.qbk +++ b/doc/concept/Body.qbk @@ -71,4 +71,13 @@ In this table: [concept_Body] +[heading Models] + +* [link beast.ref.beast__http__basic_dynamic_body `basic_dynamic_body`] +* [link beast.ref.beast__http__buffer_body `buffer_body`] +* [link beast.ref.beast__http__dynamic_body `dynamic_body`] +* [link beast.ref.beast__http__empty_body `empty_body`] +* [link beast.ref.beast__http__string_body `string_body`] +* [link beast.ref.beast__http__string_view_body `string_view_body`] + [endsect] diff --git a/doc/concept/DynamicBuffer.qbk b/doc/concept/DynamicBuffer.qbk index 7583790d..c9abd7df 100644 --- a/doc/concept/DynamicBuffer.qbk +++ b/doc/concept/DynamicBuffer.qbk @@ -123,4 +123,14 @@ In this table: ] ] +[heading Models] + +* [link beast.ref.beast__basic_flat_buffer `basic_flat_buffer`] +* [link beast.ref.beast__basic_multi_buffer `basic_multi_buffer`] +* [link beast.ref.beast__drain_buffer `drain_buffer`] +* [link beast.ref.beast__flat_buffer `flat_buffer`] +* [link beast.ref.beast__multi_buffer `multi_buffer`] +* [link beast.ref.beast__static_buffer `static_buffer`] +* [link beast.ref.beast__static_buffer_n `static_buffer_n`] + [endsect] diff --git a/doc/concept/Fields.qbk b/doc/concept/Fields.qbk index df2f7d42..56cc9126 100644 --- a/doc/concept/Fields.qbk +++ b/doc/concept/Fields.qbk @@ -129,4 +129,9 @@ In this table: [concept_Fields] +[heading Models] + +* [link beast.ref.beast__http__basic_fields `basic_fields`] +* [link beast.ref.beast__http__fields `fields`] + [endsect] diff --git a/test/http/doc_snippets.cpp b/test/http/doc_snippets.cpp index acd2d6ac..304fbf03 100644 --- a/test/http/doc_snippets.cpp +++ b/test/http/doc_snippets.cpp @@ -324,39 +324,3 @@ struct decorator //] } // doc_http_snippets - -namespace beast { -namespace http { - -#if 0 -//[http_snippet_9] - -/// Provides buffer oriented HTTP message serialization functionality. -template< - bool isRequest, - class Body, - class Fields = fields, - class ChunkDecorator = no_chunk_decorator -> -class serializer; - -/// A serializer for HTTP/1 requests -template< - class Body, - class Fields = fields, - class ChunkDecorator = no_chunk_decorator> -using request_serializer = serializer; - -/// A serializer for HTTP/1 responses -template< - class Body, - class Fields = fields, - class ChunkDecorator = no_chunk_decorator> -using response_serializer = serializer; - -//] -#endif - -} // http -} // beast -