refactor: implementation defined namespaces

This commit moves implementation details that are visible in the documentation from the detail namespace to the see_below and implementation_defined namespaces.

CMakeLists.txt

@@ -149,6 +149,7 @@ if (BOOST_URL_MRDOCS_BUILD)
     file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/mrdocs.cpp" "#include <boost/url.hpp>\n")
     add_library(boost_url_mrdocs "${CMAKE_CURRENT_BINARY_DIR}/mrdocs.cpp")
     boost_url_setup_properties(boost_url_mrdocs)
+    target_compile_definitions(boost_url_mrdocs PUBLIC BOOST_URL_MRDOCS BOOST_URL_NO_SSE2)
     return()
 endif()
 

doc/Jamfile

@@ -27,7 +27,17 @@ docca.reference reference.qbk
         <doxygen:param>DISTRIBUTE_GROUP_DOC=YES
         <doxygen:param>MACRO_EXPANSION=YES
         <doxygen:param>EXPAND_ONLY_PREDEF=YES
-        <doxygen:param>EXCLUDE_SYMBOLS=boost::urls::detail::*
+        <doxygen:param>"EXCLUDE_SYMBOLS=\\
+            boost::urls::detail::*\\
+            boost::urls::implementation_defined::*\\
+            boost::urls::see_below::*\\
+            boost::urls::grammar::detail::*\\
+            boost::urls::grammar::implementation_defined::*\\
+            boost::urls::grammar::see_below::*\\
+            boost::urls::string_token::detail::*\\
+            boost::urls::string_token::implementation_defined::*\\
+            boost::urls::string_token::see_below::*\\
+            "
         <doxygen:param>"PREDEFINED=\\
             BOOST_SYMBOL_VISIBLE \\
             BOOST_URL_DOCS \\

doc/modules/ROOT/pages/reference.adoc

@@ -253,8 +253,6 @@ xref:reference:boost/urls/grammar/recycled_ptr.adoc[`recycled_ptr`]
 
 xref:reference:boost/urls/grammar/string_view_base.adoc[`string_view_base`]
 
-xref:reference:boost/urls/grammar/unsigned_rule.adoc[`unsigned_rule`]
-
 **StringToken**
 
 xref:reference:boost/urls/string_token/append_to.adoc[`append_to`]
@@ -263,7 +261,7 @@ xref:reference:boost/urls/string_token/arg.adoc[`arg`]
 
 xref:reference:boost/urls/string_token/assign_to.adoc[`assign_to`]
 
-xref:reference:boost/urls/string_token/is_token-0a.adoc[`is_token`]
+xref:reference:boost/urls/string_token/is_token.adoc[`is_token`]
 
 xref:reference:boost/urls/string_token/preserve_size.adoc[`preserve_size`]
 
@@ -277,20 +275,24 @@ xref:reference:boost/urls/grammar/alnum_chars.adoc[`alnum_chars`]
 
 xref:reference:boost/urls/grammar/alpha_chars.adoc[`alpha_chars`]
 
-xref:reference:boost/urls/grammar/condition.adoc[`condition`]
-
 xref:reference:boost/urls/grammar/dec_octet_rule.adoc[`dec_octet_rule`]
 
 xref:reference:boost/urls/grammar/digit_chars.adoc[`digit_chars`]
 
-xref:reference:boost/urls/grammar/error.adoc[`error`]
-
 xref:reference:boost/urls/grammar/hexdig_chars.adoc[`hexdig_chars`]
 
 xref:reference:boost/urls/grammar/not_empty_rule.adoc[`not_empty_rule`]
 
+xref:reference:boost/urls/grammar/unsigned_rule.adoc[`unsigned_rule`]
+
 xref:reference:boost/urls/grammar/vchars.adoc[`vchars`]
 
+**Enums**
+
+xref:reference:boost/urls/grammar/error.adoc[`error`]
+
+xref:reference:boost/urls/grammar/condition.adoc[`condition`]
+
 **Concepts**
 
 xref:concepts/CharSet.adoc[`CharSet`]

doc/mrdocs.yml

@@ -1,12 +1,12 @@
 # Input
+source-root: ..
 input:
   # Directories that contain documented source files
   include:
     - ../include
   # Patterns to filter out the source-files in the directories
   file-patterns:
     - '*.hpp'
-source-root: ..
 
 # Filters
 filters:
@@ -34,6 +34,14 @@ filters:
       - 'boost::urls::no_value_t'
 inaccessible-members: never
 inaccessible-bases: never
+implementation-defined:
+  - 'boost::urls::implementation_defined'
+  - 'boost::urls::grammar::implementation_defined'
+  - 'boost::urls::string_token::implementation_defined'
+see-below:
+  - 'boost::urls::see_below'
+  - 'boost::urls::grammar::see_below'
+  - 'boost::urls::string_token::see_below'
 
 # Generator
 generate: adoc
@@ -65,4 +73,4 @@ multipage: true
 # The other options are set just to ensure other targets are
 # ignored even if these options are set as ON in the cache.
 #
-cmake: '-D BOOST_URL_MRDOCS_BUILD=ON -D BOOST_URL_BUILD_FUZZERS=OFF -D BOOST_URL_BUILD_EXAMPLES=OFF -D BOOST_URL_BUILD_TESTS=OFF -D BUILD_TESTING=OFF'
+cmake: '-D BOOST_URL_MRDOCS_BUILD=ON -D CMAKE_CXX_STANDARD=20 -D BOOST_URL_BUILD_FUZZERS=OFF -D BOOST_URL_BUILD_EXAMPLES=OFF -D BOOST_URL_BUILD_TESTS=OFF -D BUILD_TESTING=OFF'

include/boost/url/authority_view.hpp

@@ -1354,7 +1354,24 @@ class BOOST_URL_DECL
 
     //--------------------------------------------
 
-    // hidden friend
+    /** Format the encoded authority to the output stream
+
+        This hidden friend function serializes the encoded URL
+        to the output stream.
+
+        @par Example
+        @code
+        authority_view a( "www.example.com" );
+
+        std::cout << a << std::endl;
+        @endcode
+
+        @return A reference to the output stream, for chaining
+
+        @param os The output stream to write to
+
+        @param a The URL to write
+    */
     friend
     std::ostream&
     operator<<(

include/boost/url/decode_view.hpp

@@ -136,8 +136,17 @@ class decode_view
         dereferenced.
     */
 #ifdef BOOST_URL_DOCS
-    using iterator = __see_below__;
+    using iterator = __see_below__
 #else
+
+    /** An iterator of constant, decoded characters.
+
+        This iterator is used to access the encoded
+        string as a bidirectional range of characters
+        with percent-decoding applied. Escape sequences
+        are not decoded until the iterator is
+        dereferenced.
+    */
     class iterator;
 #endif
 
@@ -575,6 +584,12 @@ class decode_view
     }
 public:
 
+    /// Compare two decode views for equality
+    /**
+     * This function is only enabled if both types are
+     * decode_view or convertible to `core::string_view`,
+     * but not both are convertible to `core::string_view`
+     */
     template<class S0, class S1>
     BOOST_CXX14_CONSTEXPR friend auto operator==(
         S0 const& s0, S1 const& s1) noexcept ->
@@ -584,6 +599,12 @@ class decode_view
         return decode_compare(s0, s1) == 0;
     }
 
+    /// Compare two decode views for inequality
+    /**
+     * This function is only enabled if both types are
+     * decode_view or convertible to `core::string_view`,
+     * but not both are convertible to `core::string_view`
+     */
     template<class S0, class S1>
     BOOST_CXX14_CONSTEXPR friend auto operator!=(
         S0 const& s0, S1 const& s1) noexcept ->
@@ -593,6 +614,12 @@ class decode_view
         return decode_compare(s0, s1) != 0;
     }
 
+    /// Compare two decode views for less than
+    /**
+     * This function is only enabled if both types are
+     * decode_view or convertible to `core::string_view`,
+     * but not both are convertible to `core::string_view`
+     */
     template<class S0, class S1>
     BOOST_CXX14_CONSTEXPR friend auto operator<(
         S0 const& s0, S1 const& s1) noexcept ->
@@ -602,6 +629,12 @@ class decode_view
         return decode_compare(s0, s1) < 0;
     }
 
+    /// Compare two decode views for less than or equal
+    /**
+     * This function is only enabled if both types are
+     * decode_view or convertible to `core::string_view`,
+     * but not both are convertible to `core::string_view`
+     */
     template<class S0, class S1>
     BOOST_CXX14_CONSTEXPR friend auto operator<=(
         S0 const& s0, S1 const& s1) noexcept ->
@@ -611,6 +644,12 @@ class decode_view
         return decode_compare(s0, s1) <= 0;
     }
 
+    /// Compare two decode views for greater than
+    /**
+     * This function is only enabled if both types are
+     * decode_view or convertible to `core::string_view`,
+     * but not both are convertible to `core::string_view`
+     */
     template<class S0, class S1>
     BOOST_CXX14_CONSTEXPR friend auto operator>(
         S0 const& s0, S1 const& s1) noexcept ->
@@ -620,6 +659,12 @@ class decode_view
         return decode_compare(s0, s1) > 0;
     }
 
+    /// Compare two decode views for greater than or equal
+    /**
+     * This function is only enabled if both types are
+     * decode_view or convertible to `core::string_view`,
+     * but not both are convertible to `core::string_view`
+     */
     template<class S0, class S1>
     BOOST_CXX14_CONSTEXPR friend auto operator>=(
         S0 const& s0, S1 const& s1) noexcept ->
@@ -630,7 +675,17 @@ class decode_view
     }
 #endif
 
-    // hidden friend
+    /** Format the string with percent-decoding applied to the output stream
+
+        This hidden friend function serializes the decoded view
+        to the output stream.
+
+        @return A reference to the output stream, for chaining
+
+        @param os The output stream to write to
+
+        @param s The decoded view to write
+    */
     friend
     std::ostream&
     operator<<(

include/boost/url/detail/config.hpp

@@ -145,7 +145,11 @@
 #define BOOST_URL_SEE_BELOW(Type) __see_below__
 #endif
 
-
+#ifdef __cpp_lib_array_constexpr
+#define BOOST_URL_LIB_ARRAY_CONSTEXPR constexpr
+#else
+#define BOOST_URL_LIB_ARRAY_CONSTEXPR
+#endif
 
 // avoid Boost.TypeTraits for these traits
 namespace boost {

include/boost/url/detail/format_args.hpp

@@ -332,9 +332,17 @@ template <class T, class = void>
 struct formatter;
 
 } // detail
+namespace see_below {
+using format_arg = detail::format_arg;
+}
+namespace implementation_defined {
+template <class T>
+using named_arg = detail::named_arg<T>;
+}
 } // url
 } // boost
 
+
 #include <boost/url/detail/impl/format_args.hpp>
 
 #endif

include/boost/url/detail/vformat.hpp

@@ -23,13 +23,13 @@ void
 vformat_to(
     url_base& u,
     core::string_view fmt,
-    detail::format_args args);
+    format_args args);
 
 inline
 url
 vformat(
     core::string_view fmt,
-    detail::format_args args)
+    format_args args)
 {
     url u;
     vformat_to(u, fmt, args);

include/boost/url/error_types.hpp

@@ -131,6 +131,25 @@ using system_error
 #ifdef BOOST_URL_DOCS
 error_category const& generic_category();
 #else
+
+/** A function to return the generic error category used by the library
+
+    @warning This alias is no longer supported and
+    should not be used in new code. Please use
+    `core::string_view` 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.
+
+ */
 using boost::system::generic_category;
 #endif
 
@@ -155,6 +174,25 @@ using boost::system::generic_category;
 #ifdef BOOST_URL_DOCS
 error_category const& system_category();
 #else
+
+/** A function to return the system error category used by the library
+
+    @warning This alias is no longer supported and
+    should not be used in new code. Please use
+    `core::string_view` 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.
+
+ */
 using boost::system::system_category;
 #endif
 
@@ -182,6 +220,25 @@ enum errc
     __see_below__
 };
 #else
+
+/** The set of constants used for cross-platform error codes
+
+    @warning This alias is no longer supported and
+    should not be used in new code. Please use
+    `core::string_view` 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.
+
+ */
 namespace errc = boost::system::errc;
 #endif