[gcc r13-428] libstdc++: Improve doxygen docs for <regex>

[gcc r13-428] libstdc++: Improve doxygen docs for <regex>

[Jonathan Wakely]

https://gcc.gnu.org/g:1b01963a4ea87607f5af6578a49006c8fee4d527

commit r13-428-g1b01963a4ea87607f5af6578a49006c8fee4d527
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Thu May 12 12:16:17 2022 +0100

    libstdc++: Improve doxygen docs for <regex>
    
    Add @headerfile and @since tags. Improve grouping of non-member
    functions via @relates tags.
    
    Mark the std::pair base class of std::sub_match as undocumented, so that
    the docs don't show all the related non-member functions are part of the
    sub_match API. Use a new macro to re-add the data members for Doxygen
    only.
    
    libstdc++-v3/ChangeLog:
    
            * doc/doxygen/user.cfg.in (PREDEFINED): Define macro
            _GLIBCXX_DOXYGEN_ONLY to expand its argument.
            * include/bits/c++config (_GLIBCXX_DOXYGEN_ONLY): Define.
            * include/bits/regex.h: Improve doxygen docs.
            * include/bits/regex_constants.h: Likewise.
            * include/bits/regex_error.h: Likewise.

Diff:
---
 libstdc++-v3/doc/doxygen/user.cfg.in        |  1 +
 libstdc++-v3/include/bits/c++config         |  3 ++
 libstdc++-v3/include/bits/regex.h           | 60 +++++++++++++++++++++++++----
 libstdc++-v3/include/bits/regex_constants.h |  5 ++-
 libstdc++-v3/include/bits/regex_error.h     |  7 +++-
 5 files changed, 66 insertions(+), 10 deletions(-)

diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index 2dbed727013..02ce290d3ad 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -2404,6 +2404,7 @@ PREDEFINED             = __cplusplus=202002L \
                          _GLIBCXX_HAVE_BUILTIN_IS_AGGREGATE \
                          _GLIBCXX_HAVE_IS_CONSTANT_EVALUATED \
                          _GLIBCXX_HAVE_BUILTIN_LAUNDER \
+			 "_GLIBCXX_DOXYGEN_ONLY(X)=X " \
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
diff --git a/libstdc++-v3/include/bits/c++config b/libstdc++-v3/include/bits/c++config
index 150b0bc5834..191880fb99d 100644
--- a/libstdc++-v3/include/bits/c++config
+++ b/libstdc++-v3/include/bits/c++config
@@ -823,6 +823,9 @@ namespace std
 
 #undef _GLIBCXX_HAS_BUILTIN
 
+// Mark code that should be ignored by the compiler, but seen by Doxygen.
+#define _GLIBCXX_DOXYGEN_ONLY(X)
+
 // PSTL configuration
 
 #if __cplusplus >= 201703L
diff --git a/libstdc++-v3/include/bits/regex.h b/libstdc++-v3/include/bits/regex.h
index 46c168010bf..24298e35e2c 100644
--- a/libstdc++-v3/include/bits/regex.h
+++ b/libstdc++-v3/include/bits/regex.h
@@ -84,6 +84,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
    * The class %regex is parameterized around a set of related types and
    * functions used to complete the definition of its semantics.  This class
    * satisfies the requirements of such a traits class.
+   *
+   * @headerfile regex
+   * @since C++11
    */
   template<typename _Ch_type>
     class regex_traits
@@ -388,11 +391,24 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 
   // [7.8] Class basic_regex
   /**
-   * Objects of specializations of this class represent regular expressions
-   * constructed from sequences of character type @p _Ch_type.
+   * @brief A regular expression
+   *
+   * Specializations of this class template represent regular expressions
+   * constructed from sequences of character type `_Ch_type`.
+   * Use the `std::regex` typedef for `std::basic_regex<char>`.
+   *
+   * A character sequence passed to the constructor will be parsed according
+   * to the chosen grammar, and used to create a state machine representing
+   * the regular expression. The regex object can then be passed to algorithms
+   * such as `std::regex_match` to match sequences of characters.
+   *
+   * The `syntax_option_type` flag passed to the constructor selects from
+   * one of the supported regular expression grammars. The default is
+   * `ECMAScript` and the others are `basic`, `extended`, `awk`, `grep`, and
+   * `egrep`, which are variations on POSIX regular expressions.
    *
-   * Storage for the regular expression is allocated and deallocated as
-   * necessary by the member functions of this class.
+   * @headerfile regex
+   * @since C++11
    */
   template<typename _Ch_type, typename _Rx_traits = regex_traits<_Ch_type>>
     class basic_regex
@@ -885,14 +901,22 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
    * An object of this class is essentially a pair of iterators marking a
    * matched subexpression within a regular expression pattern match. Such
    * objects can be converted to and compared with std::basic_string objects
-   * of a similar base character type as the pattern matched by the regular
+   * of the same character type as the pattern matched by the regular
    * expression.
    *
+   * A `sub_match<Iter>` has a public base class of type `pair<Iter, Iter>`,
+   * so inherits pair's data members named `first` and `second`.
    * The iterators that make up the pair are the usual half-open interval
    * referencing the actual original pattern matched.
+   *
+   * @headerfile regex
+   * @since C++11
    */
   template<typename _BiIter>
-    class sub_match : public std::pair<_BiIter, _BiIter>
+    class sub_match
+    /// @cond undocumented
+    : public std::pair<_BiIter, _BiIter>
+    /// @endcond
     {
       typedef iterator_traits<_BiIter>			__iter_traits;
 	
@@ -902,6 +926,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       typedef _BiIter					iterator;
       typedef basic_string<value_type>			string_type;
 
+      _GLIBCXX_DOXYGEN_ONLY(iterator first; iterator second;)
+
       bool matched;
 
       constexpr sub_match() noexcept : matched() { }
@@ -1699,6 +1725,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
    * of characters [first, second) which formed that match. Otherwise matched
    * is false, and members first and second point to the end of the sequence
    * that was searched.
+   *
+   * @headerfile regex
+   * @since C++11
    */
   template<typename _Bi_iter,
 	   typename _Alloc = allocator<sub_match<_Bi_iter> > >
@@ -2125,6 +2154,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
    * @brief Compares two match_results for equality.
    * @returns true if the two objects refer to the same match,
    *          false otherwise.
+   *
+   * @relates match_results
    */
   template<typename _Bi_iter, typename _Alloc>
     inline bool
@@ -2150,6 +2181,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
    * @brief Compares two match_results for inequality.
    * @returns true if the two objects do not refer to the same match,
    *          false otherwise.
+   *
+   * @relates match_results
    */
   template<typename _Bi_iter, class _Alloc>
     inline bool
@@ -2165,6 +2198,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
    * @param __rhs A match result.
    *
    * The contents of the two match_results objects are swapped.
+   *
+   * @relates match_results
    */
   template<typename _Bi_iter, typename _Alloc>
     inline void
@@ -2177,8 +2212,9 @@ _GLIBCXX_END_NAMESPACE_CXX11
   // [28.11.2] Function template regex_match
   /**
    * @name Matching, Searching, and Replacing
+   *
+   * @{
    */
-  ///@{
 
   /**
    * @brief Determines if there is a match between the regular expression @p e
@@ -2486,6 +2522,7 @@ _GLIBCXX_END_NAMESPACE_CXX11
 
   // std [28.11.4] Function template regex_replace
 
+  /// @cond undocumented
   template<typename _Out_iter, typename _Bi_iter,
 	   typename _Rx_traits, typename _Ch_type>
     _Out_iter
@@ -2493,6 +2530,7 @@ _GLIBCXX_END_NAMESPACE_CXX11
 		    const basic_regex<_Ch_type, _Rx_traits>& __e,
 		    const _Ch_type* __fmt, size_t __len,
 		    regex_constants::match_flag_type __flags);
+  /// @endcond
 
   /**
    * @brief Search for a regular expression within a range for multiple times,
@@ -2654,7 +2692,7 @@ _GLIBCXX_END_NAMESPACE_CXX11
       return __result;
     }
 
-  ///@}
+  /// @}
 
 _GLIBCXX_BEGIN_NAMESPACE_CXX11
 
@@ -2662,6 +2700,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
   /**
    * An iterator adaptor that will provide repeated calls of regex_search over
    * a range until no more matches remain.
+   *
+   * @headerfile regex
+   * @since C++11
    */
   template<typename _Bi_iter,
 	   typename _Ch_type = typename iterator_traits<_Bi_iter>::value_type,
@@ -2779,6 +2820,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
    * The purpose of this iterator is to enumerate all, or all specified,
    * matches of a regular expression within a text range.  The dereferenced
    * value of an iterator of this class is a std::sub_match object.
+   *
+   * @headerfile regex
+   * @since C++11
    */
   template<typename _Bi_iter,
 	   typename _Ch_type = typename iterator_traits<_Bi_iter>::value_type,
diff --git a/libstdc++-v3/include/bits/regex_constants.h b/libstdc++-v3/include/bits/regex_constants.h
index 35a8956b447..c7e1d857b1f 100644
--- a/libstdc++-v3/include/bits/regex_constants.h
+++ b/libstdc++-v3/include/bits/regex_constants.h
@@ -1,4 +1,4 @@
-// class template regex -*- C++ -*-
+// Namespace std::regex_constants -*- C++ -*-
 
 // Copyright (C) 2010-2022 Free Software Foundation, Inc.
 //
@@ -38,6 +38,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
  * @defgroup regex Regular Expressions
  *
  * A facility for performing regular expression pattern matching.
+ *
+ * @since C++11
+ *
  * @{
  */
 
diff --git a/libstdc++-v3/include/bits/regex_error.h b/libstdc++-v3/include/bits/regex_error.h
index 77d4925921b..74a1428c2c7 100644
--- a/libstdc++-v3/include/bits/regex_error.h
+++ b/libstdc++-v3/include/bits/regex_error.h
@@ -1,4 +1,4 @@
-// class template regex -*- C++ -*-
+// Errors for std::regex -*- C++ -*-
 
 // Copyright (C) 2010-2022 Free Software Foundation, Inc.
 //
@@ -130,6 +130,9 @@ namespace regex_constants
    * @ingroup exceptions
    *
    * The regular expression library throws objects of this class on error.
+   *
+   * @headerfile regex
+   * @since C++11
    */
   class regex_error : public std::runtime_error
   {
@@ -158,6 +161,7 @@ namespace regex_constants
     { return _M_code; }
 
   private:
+    /// @cond undocumented
     regex_error(error_type __ecode, const char* __what)
     : std::runtime_error(__what), _M_code(__ecode)
     { }
@@ -167,6 +171,7 @@ namespace regex_constants
     __throw_regex_error(error_type __ecode __attribute__((__unused__)),
 			const char* __what __attribute__((__unused__)))
     { _GLIBCXX_THROW_OR_ABORT(regex_error(__ecode, __what)); }
+    /// @endcond
   };
 
   /// @cond undocumented