docs: clang format javadoc

include/boost/url/detail/config.hpp

@@ -131,6 +131,16 @@
 #define BOOST_URL_DEPRECATED(msg) BOOST_DEPRECATED(msg)
 #endif
 
+// Implementation defined type for Doxygen while Clang
+// can still parse the comments into the AST
+#ifndef BOOST_URL_DOCS
+#define BOOST_URL_IMPLEMENTATION_DEFINED(Type) Type
+#else
+#define BOOST_URL_IMPLEMENTATION_DEFINED(Type) __implementation_defined__
+#endif
+
+
+
 // avoid Boost.TypeTraits for these traits
 namespace boost {
 namespace urls {

include/boost/url/format.hpp

@@ -400,11 +400,7 @@ format_to(
 
 */
 template <class T>
-#ifdef BOOST_URL_DOCS
-__implementation_defined__
-#else
-detail::named_arg<T>
-#endif
+BOOST_URL_IMPLEMENTATION_DEFINED(detail::named_arg<T>)
 arg(core::string_view name, T const& arg)
 {
     return {name, arg};

include/boost/url/grammar/string_token.hpp

@@ -67,12 +67,22 @@ struct arg
     */
     virtual char* prepare(std::size_t n) = 0;
 
-    // prevent misuse
+    /// Virtual destructor
     virtual ~arg() = default;
+
+    /// Default constructor
     arg() = default;
+
+    /// Default move constructor
     arg(arg&&) = default;
+
+    /// Deleted copy constructor
     arg(arg const&) = delete;
+
+    /// Deleted move assignment
     arg& operator=(arg&&) = delete;
+
+    /// Deleted copy assignment
     arg& operator=(arg const&) = delete;
 };
 
@@ -84,9 +94,13 @@ struct arg
 template<class T>
 using is_token = __see_below__;
 #else
+/** Metafunction returning true if T is a StringToken
+ */
 template<class T, class = void>
 struct is_token : std::false_type {};
 
+/** Metafunction returning true if T is a StringToken
+ */
 template<class T>
 struct is_token<T, void_t<
     decltype(std::declval<T&>().prepare(
@@ -189,6 +203,8 @@ struct append_to_t
     string_type& s_;
 };
 
+/** Create a token for appending to a plain string
+ */
 template<
     class Alloc =
         std::allocator<char>>
@@ -252,6 +268,8 @@ struct assign_to_t
     string_type& s_;
 };
 
+/** A token for assigning to a plain string
+ */
 template<
     class Alloc =
         std::allocator<char>>
@@ -321,6 +339,8 @@ struct preserve_size_t
     std::size_t n_ = 0;
 };
 
+/** A token for producing a durable core::string_view from a temporary string
+ */
 template<
     class Alloc =
         std::allocator<char>>

include/boost/url/ignore_case.hpp

@@ -29,11 +29,7 @@ struct ignore_case_t
     comparisons should be case-insensitive.
 */
 constexpr
-#ifdef BOOST_URL_DOCS
-__implementation_defined__
-#else
-ignore_case_t
-#endif
+BOOST_URL_IMPLEMENTATION_DEFINED(ignore_case_t)
 ignore_case{};
 
 /** An optional parameter to determine case-sensitivity

include/boost/url/optional.hpp

@@ -16,6 +16,7 @@
 namespace boost {
 namespace urls {
 
+#ifndef BOOST_URL_DOCS
 /** The type of optional used by the library
 
     @warning This alias is no longer supported and
@@ -34,12 +35,29 @@ namespace urls {
     the library.
 
 */
-#ifndef BOOST_URL_DOCS
 template<class T>
 using optional
     BOOST_URL_DEPRECATED("Use boost::optional<T> instead") =
     boost::optional<T>;
 #else
+/** The type of optional used by the library
+
+    @warning This alias is no longer supported and
+    should not be used in new code. Please use
+    `boost::optional` instead.
+
+    This alias is included for backwards
+    compatibility with earlier versions of the
+    library.
+
+    However, it will be removed in future releases,
+    and using it in new code is not recommended.
+
+    Please use the updated version instead to
+    ensure compatibility with future versions of
+    the library.
+
+*/
 template<class T>
 using optional = boost::optional<T>;
 #endif

include/boost/url/rfc/absolute_uri_rule.hpp

@@ -65,6 +65,38 @@ struct absolute_uri_rule_t
         system::result<value_type>;
 };
 
+/** Rule for absolute-URI
+
+    @par Value Type
+    @code
+    using value_type = url_view;
+    @endcode
+
+    @par Example
+    Rules are used with the function @ref grammar::parse.
+    @code
+    system::result< url_view > rv = grammar::parse( "http://example.com/index.htm?id=1", absolute_uri_rule );
+    @endcode
+
+    @par BNF
+    @code
+    absolute-URI    = scheme ":" hier-part [ "?" query ]
+
+    hier-part       = "//" authority path-abempty
+                    / path-absolute
+                    / path-rootless
+                    / path-empty
+    @endcode
+
+    @par Specification
+    @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-4.3"
+        >4.3. Absolute URI (rfc3986)</a>
+
+    @see
+        @ref grammar::parse,
+        @ref parse_absolute_uri,
+        @ref url_view.
+*/
 constexpr absolute_uri_rule_t absolute_uri_rule{};
 #endif
 

include/boost/url/rfc/authority_rule.hpp

@@ -60,6 +60,33 @@ struct authority_rule_t
         system::result<value_type>;
 };
 
+/** Rule for authority
+
+    @par Value Type
+    @code
+    using value_type = authority_view;
+    @endcode
+
+    @par Example
+    Rules are used with the function @ref grammar::parse.
+    @code
+    system::result< authority_view > rv = grammar::parse( "user:pass@example.com:8080", authority_rule );
+    @endcode
+
+    @par BNF
+    @code
+    authority   = [ userinfo "@" ] host [ ":" port ]
+    @endcode
+
+    @par Specification
+    @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2"
+        >3.2. Authority (rfc3986)</a>
+
+    @see
+        @ref authority_view,
+        @ref grammar::parse,
+        @ref parse_authority.
+*/
 constexpr authority_rule_t authority_rule{};
 #endif
 

include/boost/url/rfc/ipv4_address_rule.hpp

@@ -69,6 +69,41 @@ struct ipv4_address_rule_t
         system::result<ipv4_address>;
 };
 
+/** Rule for an IP version 4 style address
+
+    @par Value Type
+    @code
+    using value_type = ipv4_address;
+    @endcode
+
+    @par Example
+    Rules are used with the function @ref grammar::parse.
+    @code
+    system::result< ipv4_address > rv = grammar::parse( "192.168.0.1", ipv4_address_rule );
+    @endcode
+
+    @par BNF
+    @code
+    IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
+
+    dec-octet   = DIGIT                 ; 0-9
+                / %x31-39 DIGIT         ; 10-99
+                / "1" 2DIGIT            ; 100-199
+                / "2" %x30-34 DIGIT     ; 200-249
+                / "25" %x30-35          ; 250-255
+    @endcode
+
+    @par Specification
+    @li <a href="https://en.wikipedia.org/wiki/IPv4"
+        >IPv4 (Wikipedia)</a>
+    @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
+        >3.2.2. Host (rfc3986)</a>
+
+    @see
+        @ref ipv4_address,
+        @ref parse_ipv4_address,
+        @ref grammar::parse.
+*/
 constexpr ipv4_address_rule_t ipv4_address_rule{};
 #endif
 

include/boost/url/rfc/ipv6_address_rule.hpp

@@ -77,6 +77,49 @@ struct ipv6_address_rule_t
         system::result<ipv6_address>;
 };
 
+/** Rule for An IP version 6 style address
+
+    @par Value Type
+    @code
+    using value_type = ipv6_address;
+    @endcode
+
+    @par Example
+    Rules are used with the function @ref grammar::parse.
+    @code
+    system::result< ipv6_address > rv = grammar::parse( "2001:0db8:85a3:0000:0000:8a2e:0370:7334", ipv6_address_rule );
+    @endcode
+
+    @par BNF
+    @code
+    IPv6address =                            6( h16 ":" ) ls32
+                /                       "::" 5( h16 ":" ) ls32
+                / [               h16 ] "::" 4( h16 ":" ) ls32
+                / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
+                / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
+                / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
+                / [ *4( h16 ":" ) h16 ] "::"              ls32
+                / [ *5( h16 ":" ) h16 ] "::"              h16
+                / [ *6( h16 ":" ) h16 ] "::"
+
+    ls32        = ( h16 ":" h16 ) / IPv4address
+                ; least-significant 32 bits of address
+
+    h16         = 1*4HEXDIG
+                ; 16 bits of address represented in hexadecimal
+    @endcode
+
+    @par Specification
+    @li <a href="https://datatracker.ietf.org/doc/html/rfc4291"
+        >IP Version 6 Addressing Architecture (rfc4291)</a>
+    @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
+        >3.2.2. Host (rfc3986)</a>
+
+    @see
+        @ref ipv6_address,
+        @ref parse_ipv6_address,
+        @ref grammar::parse.
+*/
 constexpr ipv6_address_rule_t ipv6_address_rule{};
 #endif
 

include/boost/url/rfc/origin_form_rule.hpp

@@ -63,6 +63,37 @@ struct origin_form_rule_t
             ) const noexcept;
 };
 
+/** Rule for origin-form
+
+    This appears in the HTTP/1 request-line grammar.
+
+    @par Value Type
+    @code
+    using value_type = url_view;
+    @endcode
+
+    @par Example
+    Rules are used with the function @ref grammar::parse.
+    @code
+    system::result< url_view > rv = grammar::parse( "/index.htm?layout=mobile", origin_form_rule );
+    @endcode
+
+    @par BNF
+    @code
+    origin-form    = absolute-path [ "?" query ]
+
+    absolute-path = 1*( "/" segment )
+    @endcode
+
+    @par Specification
+    @li <a href="https://datatracker.ietf.org/doc/html/rfc7230#section-5.3.1"
+        >5.3.1.  origin-form (rfc7230)</a>
+
+    @see
+        @ref grammar::parse,
+        @ref parse_origin_form,
+        @ref url_view.
+*/
 constexpr origin_form_rule_t origin_form_rule{};
 #endif
 

include/boost/url/rfc/pct_encoded_rule.hpp

@@ -94,6 +94,45 @@ struct pct_encoded_rule_t
     CharSet cs_;
 };
 
+/** Rule for a string with percent-encoded escapes
+
+    This function returns a rule which matches
+    a percent-encoded string, permitting characters
+    in the string which are also in the specified
+    character set to be used unescaped.
+
+    @par Value Type
+    @code
+    using value_type = pct_string_view;
+    @endcode
+
+    @par Example
+    Rules are used with the function @ref grammar::parse.
+    @code
+    //  pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"
+
+    system::result< pct_string_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( pchars ) );
+    @endcode
+
+    @par BNF
+    @code
+    pct-encoded   = "%" HEXDIG HEXDIG
+    @endcode
+
+    @param cs The character set indicating
+    which characters are allowed without escapes.
+    Any character which is not in this set must be
+    escaped, or else parsing returns an error.
+
+    @par Specification
+    @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-2.1">
+        2.1. Percent-Encoding (rfc3986)</a>
+
+    @see
+        @ref grammar::parse,
+        @ref pchars,
+        @ref pct_string_view.
+*/
 template<class CharSet>
 constexpr
 auto