Tidy up documentation:

fix #135

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

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
-