From: Jonathan Wakely <jwakely@redhat.com>
To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org
Subject: [committed 07/12] libstdc++: Improve doxygen docs for <regex>
Date: Fri, 13 May 2022 13:40:45 +0100 [thread overview]
Message-ID: <20220513124050.4028450-7-jwakely@redhat.com> (raw)
In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com>
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
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.
---
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
*
- * Storage for the regular expression is allocated and deallocated as
- * necessary by the member functions of this class.
+ * 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.
+ *
+ * @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
--
2.34.1
next prev parent reply other threads:[~2022-05-13 12:41 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
2022-05-13 12:40 ` [committed 02/12] libstdc++: Fix typo in doxygen @headerfile command Jonathan Wakely
2022-05-13 12:40 ` [committed 03/12] libstdc++: Add macros for the inline namespace std::_V2 Jonathan Wakely
2022-05-14 15:36 ` François Dumont
2022-05-16 4:27 ` François Dumont
2022-05-16 16:19 ` Jonathan Wakely
2022-05-16 17:04 ` François Dumont
2022-05-16 16:13 ` Jonathan Wakely
2022-05-16 16:59 ` François Dumont
2022-05-13 12:40 ` [committed 04/12] libstdc++: Improve doxygen docs for std::pointer_traits Jonathan Wakely
2022-05-13 12:40 ` [committed 05/12] libstdc++: Improve doxygen docs for <system_error> Jonathan Wakely
2022-05-13 12:40 ` [committed 06/12] libstdc++: Improve doxygen docs for <atomic> Jonathan Wakely
2022-05-13 12:40 ` Jonathan Wakely [this message]
2022-05-13 12:40 ` [committed 08/12] libstdc++: Improve doxygen docs for std::allocator Jonathan Wakely
2022-05-13 12:40 ` [committed 09/12] libstdc++: Improve doxygen docs for algorithms and more Jonathan Wakely
2022-05-13 12:40 ` [committed 10/12] libstdc++: Improve doxygen docs for <thread> and <future> Jonathan Wakely
2022-05-13 12:40 ` [committed 11/12] libstdc++: Improve doxygen docs for some of <memory> Jonathan Wakely
2022-05-13 12:40 ` [committed 12/12] libstdc++: Improve doxygen docs for <mutex> Jonathan Wakely
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220513124050.4028450-7-jwakely@redhat.com \
--to=jwakely@redhat.com \
--cc=gcc-patches@gcc.gnu.org \
--cc=libstdc++@gcc.gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).