* include/bits/regex.h: Improve docs.
* include/bits/regex.tcc: Do not document implementation details.
Tested powerpc64le-linux. Committed to trunk.
commit abbe3b64701718dc3327039127a07547391e29d2
Author: Jonathan Wakely <jwak...@redhat.com>
Date: Tue May 7 15:10:12 2019 +0100
Improve API docs for std::regex
* include/bits/regex.h: Improve docs.
* include/bits/regex.tcc: Do not document implementation details.
diff --git a/libstdc++-v3/include/bits/regex.h
b/libstdc++-v3/include/bits/regex.h
index 7576cd7a9c0..76219b5ae3b 100644
--- a/libstdc++-v3/include/bits/regex.h
+++ b/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
*/
diff --git a/libstdc++-v3/include/bits/regex.tcc
b/libstdc++-v3/include/bits/regex.tcc
index 1c8625dc8e8..dbe348dbfe8 100644
--- a/libstdc++-v3/include/bits/regex.tcc
+++ b/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
