Tidy up documentation:

fix #135

* Fix broken references
* Move doc debug headers to extras/
* Add rfc7230 utility classes to quick reference

CHANGELOG.md

@@ -8,6 +8,7 @@
 * Fix Reader concept doc typo
 * Add is_Reader trait
 * Tidy up basic_headers for documentation
+* Tidy up documentation
 
 API Changes:
 

doc/quickref.xml

@@ -16,10 +16,10 @@
     <colspec colname="d"/>
     <thead>
       <row>
-        <entry valign="center" namest="a" nameend="b">
+        <entry valign="center" namest="a" nameend="c">
           <bridgehead renderas="sect2">HTTP</bridgehead>
         </entry>
-        <entry valign="center" namest="c" nameend="d">
+        <entry valign="center" namest="d" nameend="d">
           <bridgehead renderas="sect2">WebSocket</bridgehead>
         </entry>
       </row>
@@ -36,6 +36,7 @@
             <member><link linkend="beast.ref.http__headers">headers</link></member>
             <member><link linkend="beast.ref.http__message">message</link></member>
             <member><link linkend="beast.ref.http__message_headers">message_headers</link></member>
+            <member><link linkend="beast.ref.http__parser_v1">parser_v1</link></member>
             <member><link linkend="beast.ref.http__request">request</link></member>
             <member><link linkend="beast.ref.http__request_headers">request_headers</link></member>
             <member><link linkend="beast.ref.http__response">response</link></member>
@@ -44,20 +45,11 @@
             <member><link linkend="beast.ref.http__streambuf_body">streambuf_body</link></member>
             <member><link linkend="beast.ref.http__string_body">string_body</link></member>
           </simplelist>
-          <bridgehead renderas="sect3">Options</bridgehead>
+          <bridgehead renderas="sect3">rfc7230</bridgehead>
           <simplelist type="vert" columns="1">
-            <member><link linkend="beast.ref.http__body_max_size">body_max_size</link></member>
+           <member><link linkend="beast.ref.http__ext_list">ext_list</link></member>
-            <member><link linkend="beast.ref.http__headers_max_size">headers_max_size</link></member>
+           <member><link linkend="beast.ref.http__param_list">param_list</link></member>
-            <member><link linkend="beast.ref.http__skip_body">skip_body</link></member>
+           <member><link linkend="beast.ref.http__token_list">token_list</link></member>
-          </simplelist>
-          <bridgehead renderas="sect3">Type Traits</bridgehead>
-          <simplelist type="vert" columns="1">
-           <member><link linkend="beast.ref.http__is_Body">is_Body</link></member>
-           <member><link linkend="beast.ref.http__is_Parser">is_Parser</link></member>
-           <member><link linkend="beast.ref.http__is_Reader">is_Reader</link></member>
-           <member><link linkend="beast.ref.http__is_Writer">is_Reader</link></member>
-           <member><link linkend="beast.ref.http__has_reader">has_reader</link></member>
-           <member><link linkend="beast.ref.http__has_writer">has_writer</link></member>
           </simplelist>
         </entry>
         <entry valign="top">
@@ -75,6 +67,23 @@
             <member><link linkend="beast.ref.http__swap">swap</link></member>
             <member><link linkend="beast.ref.http__write">write</link></member>
           </simplelist>
+          <bridgehead renderas="sect3">Type Traits</bridgehead>
+          <simplelist type="vert" columns="1">
+           <member><link linkend="beast.ref.http__is_Body">is_Body</link></member>
+           <member><link linkend="beast.ref.http__is_Parser">is_Parser</link></member>
+           <member><link linkend="beast.ref.http__is_Reader">is_Reader</link></member>
+           <member><link linkend="beast.ref.http__is_Writer">is_Reader</link></member>
+           <member><link linkend="beast.ref.http__has_reader">has_reader</link></member>
+           <member><link linkend="beast.ref.http__has_writer">has_writer</link></member>
+          </simplelist>
+        </entry>
+        <entry valign="top">
+          <bridgehead renderas="sect3">Options</bridgehead>
+          <simplelist type="vert" columns="1">
+            <member><link linkend="beast.ref.http__body_max_size">body_max_size</link></member>
+            <member><link linkend="beast.ref.http__headers_max_size">headers_max_size</link></member>
+            <member><link linkend="beast.ref.http__skip_body">skip_body</link></member>
+          </simplelist>
           <bridgehead renderas="sect3">Constants</bridgehead>
           <simplelist type="vert" columns="1">
             <member><link linkend="beast.ref.http__body_what">body_what</link></member>
@@ -99,6 +108,11 @@
             <member><link linkend="beast.ref.websocket__reason_string">reason_string</link></member>
             <member><link linkend="beast.ref.websocket__teardown_tag">teardown_tag</link></member>
           </simplelist>
+          <bridgehead renderas="sect3">Functions</bridgehead>
+          <simplelist type="vert" columns="1">
+            <member><link linkend="beast.ref.websocket__async_teardown">async_teardown</link></member>
+            <member><link linkend="beast.ref.websocket__teardown">teardown</link></member>
+          </simplelist>
           <bridgehead renderas="sect3">Options</bridgehead>
           <simplelist type="vert" columns="1">
             <member><link linkend="beast.ref.websocket__auto_fragment">auto_fragment</link></member>
@@ -110,13 +124,6 @@
             <member><link linkend="beast.ref.websocket__read_message_max">read_message_max</link></member>
             <member><link linkend="beast.ref.websocket__write_buffer_size">write_buffer_size</link></member>
           </simplelist>
-        </entry>
-        <entry valign="top">
-          <bridgehead renderas="sect3">Functions</bridgehead>
-          <simplelist type="vert" columns="1">
-            <member><link linkend="beast.ref.websocket__async_teardown">async_teardown</link></member>
-            <member><link linkend="beast.ref.websocket__teardown">teardown</link></member>
-          </simplelist>
           <bridgehead renderas="sect3">Constants</bridgehead>
           <simplelist type="vert" columns="1">
             <member><link linkend="beast.ref.websocket__close_code">close_code</link></member>
@@ -178,7 +185,6 @@
         <entry valign="top">
           <bridgehead renderas="sect3">Type Traits</bridgehead>
           <simplelist type="vert" columns="1">
-
             <member><link linkend="beast.ref.is_AsyncReadStream">is_AsyncReadStream</link></member>
             <member><link linkend="beast.ref.is_AsyncWriteStream">is_AsyncWriteStream</link></member>
             <member><link linkend="beast.ref.is_AsyncStream">is_AsyncStream</link></member>

doc/source.dox

@@ -103,11 +103,10 @@ WARN_LOGFILE           =
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
 INPUT = \
-        ../include/beast/ \
         ../include/beast/core \
         ../include/beast/http \
         ../include/beast/websocket \
-        ../include/beast/doc_debug.hpp \
+        ../extras/beast/doc_debug.hpp \
 
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          =

include/beast/http/basic_parser_v1.hpp

@@ -44,7 +44,7 @@ enum values
 
     The default headers maximum size is 16KB (16,384 bytes).
 
-    @note Objects of this type are passed to @ref set_option.
+    @note Objects of this type are used with basic_parser_v1::set_option.
 */
 struct headers_max_size
 {
@@ -67,7 +67,7 @@ struct headers_max_size
     The default body maximum size for requests is 4MB (four
     megabytes or 4,194,304 bytes) and unlimited for responses.
 
-    @note Objects of this type are passed to @ref set_option.
+    @note Objects of this type are used with basic_parser_v1::set_option.
 */
 struct body_max_size
 {

include/beast/http/concepts.hpp

@@ -171,7 +171,7 @@ struct is_Body : std::integral_constant<bool, ...>{};
 using is_Body = detail::has_value_type<T>;
 #endif
 
-/** Determine if a @ref Body has a nested type `reader`.
+/** Determine if a @b Body has a nested type `reader`.
 
     @tparam T The type to check, which must meet the
     requirements of @b Body.
@@ -189,7 +189,7 @@ struct has_reader<T, beast::detail::void_t<
         > > : std::true_type {};
 #endif
 
-/** Determine if a @ref Body has a nested type `writer`.
+/** Determine if a @b Body has a nested type `writer`.
 
     @tparam T The type to check, which must meet the
     requirements of @b Body.

include/beast/http/parser_v1.hpp

@@ -55,7 +55,7 @@ struct parser_response
         p.set_option(skip_body{true});
     @endcode
 
-    @note Objects of this type are passed to @ref basic_parser_v1::set_option.
+    @note Objects of this type are passed to @ref parser_v1::set_option.
 */
 struct skip_body
 {
@@ -125,6 +125,11 @@ public:
 
         @param args A list of arguments forwarded to the message constructor.
     */
+#if GENERATING_DOCS
+    template<class... Args>
+    explicit
+    parser_v1(Args&&... args);
+#else
     template<class Arg1, class... ArgN,
         class = typename std::enable_if<! std::is_same<
             typename std::decay<Arg1>::type, parser_v1>::value>>
@@ -134,6 +139,7 @@ public:
             std::forward<ArgN>(argn)...)
     {
     }
+#endif
 
     /// Set the expect body option.
     void

include/beast/http/rfc7230.hpp

@@ -19,17 +19,22 @@ namespace http {
     extension. The parameter list is a series of name/value pairs
     with each pair starting with a semicolon. The value is optional.
 
-    BNF:
-    @code
-        param-list  = *( OWS ";" OWS param )
-        param       = token OWS [ "=" OWS ( token / quoted-string ) ]
-    @endcode
-
     If a parsing error is encountered while iterating the string,
     the behavior of the container will be as if a string containing
     only characters up to but excluding the first invalid character
     was used to construct the list.
 
+    @par BNF
+    @code
+        param-list  = *( OWS ";" OWS param )
+        param       = token OWS [ "=" OWS ( token / quoted-string ) ]
+    @endcode
+
+    To use this class, construct with the string to be parsed and
+    then use @ref begin and @ref end, or range-for to iterate each
+    item:
+
+    @par Example
     @code
     for(auto const& param : param_list{";level=9;no_context_takeover;bits=15"})
     {
@@ -96,7 +101,12 @@ public:
     field value. The extension list is a comma separated list of
     token parameter list pairs.
 
-    BNF:
+    If a parsing error is encountered while iterating the string,
+    the behavior of the container will be as if a string containing
+    only characters up to but excluding the first invalid character
+    was used to construct the list.
+
+    @par BNF
     @code
         ext-list    = *( "," OWS ) ext *( OWS "," [ OWS ext ] )
         ext         = token param-list
@@ -104,15 +114,11 @@ public:
         param       = token OWS [ "=" OWS ( token / quoted-string ) ]
     @endcode
 
-    If a parsing error is encountered while iterating the string,
-    the behavior of the container will be as if a string containing
-    only characters up to but excluding the first invalid character
-    was used to construct the list.
-
     To use this class, construct with the string to be parsed and
-    then use @ref begin and @end, or range-for to iterate each
+    then use @ref begin and @ref end, or range-for to iterate each
     item:
 
+    @par Example
     @code
     for(auto const& ext : ext_list{"none, 7z;level=9, zip;no_context_takeover;bits=15"})
     {
@@ -200,20 +206,21 @@ public:
     header field value. The input is a comma separated list of
     tokens.
 
-    BNF:
-    @code
-        token-list  = *( "," OWS ) token *( OWS "," [ OWS token ] )
-    @endcode
-
     If a parsing error is encountered while iterating the string,
     the behavior of the container will be as if a string containing
     only characters up to but excluding the first invalid character
     was used to construct the list.
 
+    @par BNF
+    @code
+        token-list  = *( "," OWS ) token *( OWS "," [ OWS token ] )
+    @endcode
+
     To use this class, construct with the string to be parsed and
-    then use @ref begin and @end, or range-for to iterate each
+    then use @ref begin and @ref end, or range-for to iterate each
     item:
 
+    @par Example
     @code
     for(auto const& token : token_list{"apple, pear, banana"})
         std::cout << token << "\n";
@@ -274,4 +281,3 @@ public:
 #include <beast/http/impl/rfc7230.ipp>
 
 #endif
-

include/beast/websocket/error.hpp

@@ -13,7 +13,7 @@
 namespace beast {
 namespace websocket {
 
-/// Error codes returned from @ref stream operations.
+/// Error codes returned from @ref beast::websocket::stream operations.
 enum class error
 {
     /// Both sides performed a WebSocket close

include/beast/websocket/option.hpp

@@ -30,7 +30,8 @@ namespace websocket {
 
     The default setting is to fragment messages.
 
-    @note Objects of this type are passed to @ref stream::set_option.
+    @note Objects of this type are used with
+          @ref beast::websocket::stream::set_option.
 
     @par Example
     Setting the automatic fragmentation option:
@@ -76,7 +77,8 @@ struct auto_fragment
 
     The default setting is no decorator.
 
-    @note Objects of this type are passed to @ref stream::set_option.
+    @note Objects of this type are used with
+          @ref beast::websocket::stream::set_option.
 
     @par Example
     Setting the decorator.
@@ -125,7 +127,8 @@ decorate(Decorator&& d)
     The default setting is to close connections after a failed
     upgrade request.
 
-    @note Objects of this type are passed to @ref stream::set_option.
+    @note Objects of this type are used with
+          @ref beast::websocket::stream::set_option.
 
     @par Example
     Setting the keep alive option.
@@ -160,7 +163,8 @@ struct keep_alive
 
     The default setting is opcode::text.
 
-    @note Objects of this type are passed to @ref stream::set_option.
+    @note Objects of this type are used with
+          @ref beast::websocket::stream::set_option.
 
     @par Example
     Setting the message type to binary.
@@ -190,8 +194,10 @@ struct message_type
 /** Pong callback option.
 
     Sets the callback to be invoked whenever a pong is received
-    during a call to @ref read, @ref read_frame, @ref async_read,
+    during a call to @ref beast::websocket::stream::read,
-    or @ref async_read_frame.
+    @ref beast::websocket::stream::read_frame,
+    @ref beast::websocket::stream::async_read, or
+    @ref beast::websocket::stream::async_read_frame.
 
     Unlike completion handlers, the callback will be invoked for
     each received pong during a call to any synchronous or
@@ -209,8 +215,10 @@ struct message_type
     operation, the callback will be invoked using the same method as
     that used to invoke the final handler.
 
-    @note To remove the pong callback, construct the option with
+    @note Objects of this type are used with
-    no parameters: `set_option(pong_callback{})`
+          @ref beast::websocket::stream::set_option.
+          To remove the pong callback, construct the option with
+          no parameters: `set_option(pong_callback{})`
 */
 #if GENERATING_DOCS
 using pong_callback = implementation_defined;
@@ -240,7 +248,8 @@ struct pong_callback
 
     The default is no buffering.
 
-    @note Objects of this type are passed to @ref stream::set_option.
+    @note Objects of this type are used with
+          @ref beast::websocket::stream::set_option.
 
     @par Example
     Setting the read buffer size.
@@ -272,9 +281,10 @@ struct read_buffer_size
     message size over this limit will cause a protocol failure.
 
     The default setting is 16 megabytes. A value of zero indicates
-    a limit of `std::numeric_limits<std::uint64_t>::max()`.
+    a limit of the maximum value of a `std::uint64_t`.
 
-    @note Objects of this type are passed to @ref stream::set_option.
+    @note Objects of this type are used with
+          @ref beast::websocket::stream::set_option.
 
     @par Example
     Setting the maximum read message size.
@@ -316,7 +326,8 @@ struct read_message_max
     open. Undefined behavior results if the option is modified after a
     successful WebSocket handshake.
 
-    @note Objects of this type are passed to @ref stream::set_option.
+    @note Objects of this type are used with
+          @ref beast::websocket::stream::set_option.
 
     @par Example
     Setting the write buffer size.

include/beast/websocket/stream.hpp

@@ -818,13 +818,13 @@ public:
 
         @li An error occurs on the stream.
 
-        This function is implemented in terms of one or more calls to the
+        This function is implemented in terms of one or more calls
-        next layer's `write_some` functions.
+        to the next layer's `write_some` functions.
 
         If the close reason specifies a close code other than
-        @ref close_code::none, the close frame is sent with the close
+        @ref beast::websocket::close_code::none, the close frame is
-        code and optional reason string. Otherwise, the close frame
+        sent with the close code and optional reason string. Otherwise,
-        is sent with no payload.
+        the close frame is sent with no payload.
 
         Callers should not attempt to write WebSocket data after
         initiating the close. Instead, callers should continue
@@ -847,13 +847,13 @@ public:
 
         @li An error occurs on the stream.
 
-        This function is implemented in terms of one or more calls to the
+        This function is implemented in terms of one or more calls
-        next layer's `write_some` functions.
+        to the next layer's `write_some` functions.
 
         If the close reason specifies a close code other than
-        @ref close_code::none, the close frame is sent with the close
+        @ref beast::websocket::close_code::none, the close frame is
-        code and optional reason string. Otherwise, the close frame
+        sent with the close code and optional reason string. Otherwise,
-        is sent with no payload.
+        the close frame is sent with no payload.
 
         Callers should not attempt to write WebSocket data after
         initiating the close. Instead, callers should continue
@@ -886,9 +886,9 @@ public:
         @ref stream::async_close) until this operation completes.
 
         If the close reason specifies a close code other than
-        @ref close_code::none, the close frame is sent with the close
+        @ref beast::websocket::close_code::none, the close frame is
-        code and optional reason string. Otherwise, the close frame
+        sent with the close code and optional reason string. Otherwise,
-        is sent with no payload.
+        the close frame is sent with no payload.
 
         Callers should not attempt to write WebSocket data after
         initiating the close. Instead, callers should continue

include/beast/websocket/teardown.hpp

@@ -13,13 +13,13 @@
 #include <type_traits>
 
 namespace beast {
-
 namespace websocket {
 
-/** Tag type used to find teardown and async_teardown overloads
+/** Tag type used to find @ref beast::websocket::teardown and @ref beast::websocket::async_teardown overloads
     
-    Overloads of @ref teardown and @async_teardown for user defined
+    Overloads of @ref beast::websocket::teardown and
-    types must take a value of type @ref teardown_tag in the first
+    @ref beast::websocket::async_teardown for user defined types
+    must take a value of type @ref teardown_tag in the first
     argument in order to be found by the implementation.
 */
 struct teardown_tag {};
@@ -178,7 +178,6 @@ async_teardown(teardown_tag,
     boost::asio::ip::tcp::socket& socket, TeardownHandler&& handler);
 
 } // websocket
-
 } // beast
 
 #include <beast/websocket/impl/teardown.ipp>