From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id 7827C395B424 for ; Fri, 13 May 2022 12:41:02 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 7827C395B424 Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-365-gdWd4dU1NFaRSSneBUyqcg-1; Fri, 13 May 2022 08:40:57 -0400 X-MC-Unique: gdWd4dU1NFaRSSneBUyqcg-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id EAE5E382ECD8; Fri, 13 May 2022 12:40:56 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id B024940CF8FA; Fri, 13 May 2022 12:40:56 +0000 (UTC) From: Jonathan Wakely To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 07/12] libstdc++: Improve doxygen docs for Date: Fri, 13 May 2022 13:40:45 +0100 Message-Id: <20220513124050.4028450-7-jwakely@redhat.com> In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com> References: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-13.0 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libstdc++@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libstdc++ mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 13 May 2022 12:41:04 -0000 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 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`. + * + * 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> 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` has a public base class of type `pair`, + * 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 - 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 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 > > @@ -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 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 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 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 _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::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::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