Improve API docs for std::regex

	* include/bits/regex.h: Improve docs.
	* include/bits/regex.tcc: Do not document implementation details.

From-SVN: r270952

libstdc++-v3/ChangeLog

 2019-05-07  Jonathan Wakely  <jwakely@redhat.com>
 
+	* include/bits/regex.h: Improve docs.
+	* include/bits/regex.tcc: Do not document implementation details.
+
 	* testsuite/19_diagnostics/error_code/hash.cc: New test.
 
 2019-05-06  François Dumont  <fdumont@gcc.gnu.org>

libstdc++-v3/include/bits/regex.h

@@ -838,6 +838,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
    * @brief Swaps the contents of two regular expression objects.
    * @param __lhs First regular expression.
    * @param __rhs Second regular expression.
+   * @relates basic_regex
    */
   template<typename _Ch_type, typename _Rx_traits>
     inline void
@@ -937,10 +938,12 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       { return this->_M_str().compare(__s); }
       // @}
 
+      /// @cond undocumented
       // Non-standard, used by comparison operators
       int
       _M_compare(const value_type* __s, size_t __n) const
       { return this->_M_str().compare({__s, __n}); }
+      /// @endcond
 
     private:
       // Simplified basic_string_view for C++11
@@ -1015,6 +1018,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 
   // [7.9.2] sub_match non-member operators
 
+  /// @relates sub_match @{
+
   /**
    * @brief Tests the equivalence of two regular expression submatches.
    * @param __lhs First regular expression submatch.
@@ -1081,11 +1086,14 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
     operator>(const sub_match<_BiIter>& __lhs, const sub_match<_BiIter>& __rhs)
     { return __lhs.compare(__rhs) > 0; }
 
+  /// @cond undocumented
+
   // Alias for a basic_string that can be compared to a sub_match.
   template<typename _Bi_iter, typename _Ch_traits, typename _Ch_alloc>
     using __sub_match_string = basic_string<
 			      typename iterator_traits<_Bi_iter>::value_type,
 			      _Ch_traits, _Ch_alloc>;
+  /// @endcond
 
   /**
    * @brief Tests the equivalence of a string and a regular expression
@@ -1554,6 +1562,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 	       const sub_match<_Bi_iter>& __m)
     { return __os << __m.str(); }
 
+  // @} relates sub_match
+
   // [7.10] Class template match_results
 
   /**
@@ -1575,8 +1585,6 @@ _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.
-   *
-   * @nosubgrouping
    */
   template<typename _Bi_iter,
 	   typename _Alloc = allocator<sub_match<_Bi_iter> > >
@@ -1606,7 +1614,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 
     public:
       /**
-       * @name 10.? Public Types
+       * @name 28.10 Public Types
        */
       //@{
       typedef sub_match<_Bi_iter>			   value_type;
@@ -1630,17 +1638,18 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       /**
        * @brief Constructs a default %match_results container.
        * @post size() returns 0 and str() returns an empty string.
-       * @{
        */
       match_results() : match_results(_Alloc()) { }
 
+      /**
+       * @brief Constructs a default %match_results container.
+       * @post size() returns 0 and str() returns an empty string.
+       */
       explicit
       match_results(const _Alloc& __a) noexcept
       : _Base_type(__a)
       { }
 
-      // @}
-
       /**
        * @brief Copy constructs a %match_results.
        */
@@ -1712,7 +1721,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       //@}
 
       /**
-       * @name 10.3 Element Access
+       * @name 28.10.4 Element Access
        */
       //@{
 
@@ -1837,7 +1846,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       //@}
 
       /**
-       * @name 10.4 Formatting
+       * @name 28.10.5 Formatting
        *
        * These functions perform formatted substitution of the matched
        * character sequences into their target.  The format specifiers and
@@ -1898,7 +1907,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       //@}
 
       /**
-       * @name 10.5 Allocator
+       * @name 28.10.6 Allocator
        */
       //@{
 
@@ -1912,7 +1921,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       //@}
 
       /**
-       * @name 10.6 Swap
+       * @name 28.10.7 Swap
        */
        //@{
 
@@ -1929,12 +1938,14 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       //@}
 
     private:
-      template<typename, typename, typename, bool>
-	friend class __detail::_Executor;
-
       template<typename, typename, typename>
 	friend class regex_iterator;
 
+      /// @cond undocumented
+
+      template<typename, typename, typename, bool>
+	friend class __detail::_Executor;
+
       template<typename _Bp, typename _Ap, typename _Cp, typename _Rp,
 	__detail::_RegexExecutorPolicy, bool>
 	friend bool
@@ -1971,6 +1982,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       { return _Base_type::operator[](_Base_type::size() - 1); }
 
       _Bi_iter _M_begin;
+      /// @endcond
     };
 
   typedef match_results<const char*>		 cmatch;
@@ -1981,10 +1993,11 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 #endif
 
   // match_results comparisons
+
   /**
    * @brief Compares two match_results for equality.
    * @returns true if the two objects refer to the same match,
-   * false otherwise.
+   *          false otherwise.
    */
   template<typename _Bi_iter, typename _Alloc>
     inline bool
@@ -2008,7 +2021,7 @@ _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.
+   *          false otherwise.
    */
   template<typename _Bi_iter, class _Alloc>
     inline bool
@@ -2030,9 +2043,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 	 match_results<_Bi_iter, _Alloc>& __rhs) noexcept
     { __lhs.swap(__rhs); }
 
+
 _GLIBCXX_END_NAMESPACE_CXX11
 
-  // [7.11.2] Function template regex_match
+  // [28.11.2] Function template regex_match
   /**
    * @name Matching, Searching, and Replacing
    */

libstdc++-v3/include/bits/regex.tcc

@@ -34,6 +34,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
 namespace __detail
 {
+  /// @cond undocumented
+
   // Result of merging regex_match and regex_search.
   //
   // __policy now can be _S_auto (auto dispatch) and _S_alternate (use
@@ -118,7 +120,10 @@ namespace __detail
 	}
       return __ret;
     }
-}
+  /// @endcond
+} // namespace __detail
+
+  /// @cond
 
   template<typename _Ch_type>
   template<typename _Fwd_iter>
@@ -352,7 +357,8 @@ namespace __detail
 
   template<typename _Bi_iter, typename _Alloc>
   template<typename _Out_iter>
-    _Out_iter match_results<_Bi_iter, _Alloc>::
+    _Out_iter
+    match_results<_Bi_iter, _Alloc>::
     format(_Out_iter __out,
 	   const match_results<_Bi_iter, _Alloc>::char_type* __fmt_first,
 	   const match_results<_Bi_iter, _Alloc>::char_type* __fmt_last,
@@ -667,5 +673,7 @@ namespace __detail
 	_M_result = nullptr;
     }
 
+  /// @endcond
+
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace