* [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option
@ 2022-05-13 12:40 Jonathan Wakely
2022-05-13 12:40 ` [committed 02/12] libstdc++: Fix typo in doxygen @headerfile command Jonathan Wakely
` (10 more replies)
0 siblings, 11 replies; 12+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
Before Doxygen version 1.9.2 this option is broken (see
https://github.com/doxygen/doxygen/issues/8638 for more details) and
classes are not added to the correct groups by @ingroup and @addtogroup.
Also remove the obsolete CLASS_DIAGRAMS option that causes a warning.
libstdc++-v3/ChangeLog:
* doc/doxygen/user.cfg.in (GROUP_NESTED_COMPOUNDS): Set to NO.
(CLASS_DIAGRAMS): Remove obsolete option.
---
libstdc++-v3/doc/doxygen/user.cfg.in | 11 +----------
1 file changed, 1 insertion(+), 10 deletions(-)
diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index 85955f88390..b9babc3993e 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -388,7 +388,7 @@ DISTRIBUTE_GROUP_DOC = YES
# is disabled and one has to add nested compounds explicitly via \ingroup.
# The default value is: NO.
-GROUP_NESTED_COMPOUNDS = YES
+GROUP_NESTED_COMPOUNDS = NO
# Set the SUBGROUPING tag to YES to allow class member groups of the same type
# (for instance a group of public functions) to be put as a subgroup of that
@@ -2472,15 +2472,6 @@ EXTERNAL_PAGES = YES
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
-# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram
-# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to
-# NO turns the diagrams off. Note that this option also works with HAVE_DOT
-# disabled, but it is recommended to install and use dot, since it yields more
-# powerful graphs.
-# The default value is: YES.
-
-CLASS_DIAGRAMS = YES
-
# You can include diagrams made with dia in doxygen documentation. Doxygen will
# then run dia to produce the diagram and insert it in the documentation. The
# DIA_PATH tag allows you to specify the directory where the dia binary resides.
--
2.34.1
^ permalink raw reply [flat|nested] 12+ messages in thread
* [committed 02/12] libstdc++: Fix typo in doxygen @headerfile command
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 03/12] libstdc++: Add macros for the inline namespace std::_V2 Jonathan Wakely
` (9 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* include/bits/mofunc_impl.h: Fix doxygen command.
---
libstdc++-v3/include/bits/mofunc_impl.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/libstdc++-v3/include/bits/mofunc_impl.h b/libstdc++-v3/include/bits/mofunc_impl.h
index 6cc9711a42b..405c4054642 100644
--- a/libstdc++-v3/include/bits/mofunc_impl.h
+++ b/libstdc++-v3/include/bits/mofunc_impl.h
@@ -48,7 +48,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @brief Polymorphic function wrapper.
* @ingroup functors
* @since C++23
- * @headername functional
+ * @headerfile functional
*
* The `std::move_only_function` class template is a call wrapper similar
* to * `std::function`, but does not require the stored target function
--
2.34.1
^ permalink raw reply [flat|nested] 12+ messages in thread
* [committed 03/12] libstdc++: Add macros for the inline namespace std::_V2
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 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 04/12] libstdc++: Improve doxygen docs for std::pointer_traits Jonathan Wakely
` (8 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
Unlike the rest of the series, this isn't suitable for backporting
because it changes the ABI for the gnu-versioned-namespace build. That's
fine for GCC 13, but not OK to change within a release branch, e.g.
between 12.1 and 12.2. If we want to backport it, the macro should do
the same thing whether or not _GLIBCXX_INLINE_VERSION is set.
-- >8 --
Use macros to open and close the inline namespace _V2 that is used for
ABI versioning of individual components such as chrono::system_clock.
This allows the namespace to be hidden in the docs generated by Doxygen,
so that we document std::foo instead of std::_V2::foo.
This also makes it easy to remove that namespace entirely for the
gnu-versioned-namespace build, where everything is already versioned as
std::__8 and there are no backwards compatibility guarantees.
libstdc++-v3/ChangeLog:
* doc/doxygen/user.cfg.in (PREDEFINED): Expand new macros to
nothing.
* include/bits/c++config (_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE)
(_GLIBCXX_END_INLINE_ABI_NAMESPACE): Define new macros.
* include/bits/algorithmfwd.h (_V2::__rotate): Use new macros
for the namespace.
* include/bits/chrono.h (chrono::_V2::system_clock): Likewise.
* include/bits/stl_algo.h (_V2::__rotate): Likewise.
* include/std/condition_variable (_V2::condition_variable_any):
Likewise.
* include/std/system_error (_V2::error_category): Likewise.
---
libstdc++-v3/doc/doxygen/user.cfg.in | 2 ++
libstdc++-v3/include/bits/algorithmfwd.h | 15 ++++++++-------
libstdc++-v3/include/bits/c++config | 11 +++++++++--
libstdc++-v3/include/bits/chrono.h | 4 ++--
libstdc++-v3/include/bits/stl_algo.h | 5 ++---
libstdc++-v3/include/std/condition_variable | 4 ++--
libstdc++-v3/include/std/system_error | 5 +++--
7 files changed, 28 insertions(+), 18 deletions(-)
diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index b9babc3993e..2dbed727013 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -2347,6 +2347,8 @@ PREDEFINED = __cplusplus=202002L \
"_GLIBCXX_END_NAMESPACE_CONTAINER= " \
"_GLIBCXX_END_NAMESPACE_CXX11= " \
"_GLIBCXX_END_NAMESPACE_LDBL= " \
+ "-D_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(X)= " \
+ "-D_GLIBCXX_END_INLINE_ABI_NAMESPACE(X)= " \
"_GLIBCXX_TEMPLATE_ARGS=... " \
"_GLIBCXX_DEPRECATED= " \
"_GLIBCXX_DEPRECATED_SUGGEST(E)= " \
diff --git a/libstdc++-v3/include/bits/algorithmfwd.h b/libstdc++-v3/include/bits/algorithmfwd.h
index 5271a90b501..aacc34e09e8 100644
--- a/libstdc++-v3/include/bits/algorithmfwd.h
+++ b/libstdc++-v3/include/bits/algorithmfwd.h
@@ -601,13 +601,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_OIter
reverse_copy(_BIter, _BIter, _OIter);
- inline namespace _V2
- {
- template<typename _FIter>
- _GLIBCXX20_CONSTEXPR
- _FIter
- rotate(_FIter, _FIter, _FIter);
- }
+_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
+
+ template<typename _FIter>
+ _GLIBCXX20_CONSTEXPR
+ _FIter
+ rotate(_FIter, _FIter, _FIter);
+
+_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
template<typename _FIter, typename _OIter>
_GLIBCXX20_CONSTEXPR
diff --git a/libstdc++-v3/include/bits/c++config b/libstdc++-v3/include/bits/c++config
index 2798b9786dc..150b0bc5834 100644
--- a/libstdc++-v3/include/bits/c++config
+++ b/libstdc++-v3/include/bits/c++config
@@ -345,13 +345,16 @@ namespace __gnu_cxx
# define _GLIBCXX_DEFAULT_ABI_TAG
#endif
-// Defined if inline namespaces are used for versioning.
+// Non-zero if inline namespaces are used for versioning the entire library.
#define _GLIBCXX_INLINE_VERSION
-// Inline namespace for symbol versioning.
#if _GLIBCXX_INLINE_VERSION
+// Inline namespace for symbol versioning of (nearly) everything in std.
# define _GLIBCXX_BEGIN_NAMESPACE_VERSION namespace __8 {
# define _GLIBCXX_END_NAMESPACE_VERSION }
+// Unused when everything in std is versioned anyway.
+# define _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(X)
+# define _GLIBCXX_END_INLINE_ABI_NAMESPACE(X)
namespace std
{
@@ -376,8 +379,12 @@ _GLIBCXX_END_NAMESPACE_VERSION
}
#else
+// Unused.
# define _GLIBCXX_BEGIN_NAMESPACE_VERSION
# define _GLIBCXX_END_NAMESPACE_VERSION
+// Used to version individual components, e.g. std::_V2::error_category.
+# define _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(X) inline namespace X {
+# define _GLIBCXX_END_INLINE_ABI_NAMESPACE(X) } // inline namespace X
#endif
// Inline namespaces for special modes: debug, parallel.
diff --git a/libstdc++-v3/include/bits/chrono.h b/libstdc++-v3/include/bits/chrono.h
index 421898516ae..745f9a81357 100644
--- a/libstdc++-v3/include/bits/chrono.h
+++ b/libstdc++-v3/include/bits/chrono.h
@@ -1099,7 +1099,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// compatibility definitions for previous versions. At some
// point, when these clocks settle down, the inlined namespaces
// can be removed. XXX GLIBCXX_ABI Deprecated
- inline namespace _V2 {
+_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
/**
* @brief System clock.
@@ -1171,7 +1171,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*/
using high_resolution_clock = system_clock;
- } // end inline namespace _V2
+_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
#if __cplusplus >= 202002L
/// @addtogroup chrono
diff --git a/libstdc++-v3/include/bits/stl_algo.h b/libstdc++-v3/include/bits/stl_algo.h
index 1f07b9e6589..6619ff7bf1d 100644
--- a/libstdc++-v3/include/bits/stl_algo.h
+++ b/libstdc++-v3/include/bits/stl_algo.h
@@ -1190,8 +1190,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return __m;
}
- inline namespace _V2
- {
+_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
/// This is a helper function for the rotate algorithm.
template<typename _ForwardIterator>
@@ -1398,7 +1397,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
std::__iterator_category(__first));
}
- } // namespace _V2
+_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
/**
* @brief Copy a sequence, rotating its elements.
diff --git a/libstdc++-v3/include/std/condition_variable b/libstdc++-v3/include/std/condition_variable
index 2a23e65bbd3..06c4ff9ebdd 100644
--- a/libstdc++-v3/include/std/condition_variable
+++ b/libstdc++-v3/include/std/condition_variable
@@ -234,7 +234,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
void (*_M_cb)(void*);
};
- inline namespace _V2 {
+_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
/// condition_variable_any
// Like above, but mutex is not required to have try_lock.
@@ -439,7 +439,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif
};
- } // end inline namespace
+_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
/// @} group condition_variables
_GLIBCXX_END_NAMESPACE_VERSION
diff --git a/libstdc++-v3/include/std/system_error b/libstdc++-v3/include/std/system_error
index 45a1d283556..dcef94e16e2 100644
--- a/libstdc++-v3/include/std/system_error
+++ b/libstdc++-v3/include/std/system_error
@@ -77,7 +77,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif // C++17
/// @}
- inline namespace _V2 {
+_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
/** @addtogroup diagnostics
* @{
@@ -168,7 +168,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_GLIBCXX_CONST const error_category& system_category() noexcept;
/// @}
- } // end inline namespace
+
+_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
/** @addtogroup diagnostics
* @{
--
2.34.1
^ permalink raw reply [flat|nested] 12+ messages in thread
* [committed 04/12] libstdc++: Improve doxygen docs for std::pointer_traits
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-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 05/12] libstdc++: Improve doxygen docs for <system_error> Jonathan Wakely
` (7 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* include/bits/ptr_traits.h: Add some doxygen comments.
---
libstdc++-v3/include/bits/ptr_traits.h | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/libstdc++-v3/include/bits/ptr_traits.h b/libstdc++-v3/include/bits/ptr_traits.h
index 047efa5cf28..8360c3b6557 100644
--- a/libstdc++-v3/include/bits/ptr_traits.h
+++ b/libstdc++-v3/include/bits/ptr_traits.h
@@ -47,6 +47,8 @@ namespace std _GLIBCXX_VISIBILITY(default)
{
_GLIBCXX_BEGIN_NAMESPACE_VERSION
+ /// @cond undocumented
+
class __undefined;
// For a specialization `SomeTemplate<T, Types...>` the member `type` is T,
@@ -91,6 +93,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
using __ptr_traits_elem_t = typename __ptr_traits_elem<_Ptr>::type;
#endif
+ /// @endcond
+
// Define pointer_traits<P>::pointer_to.
template<typename _Ptr, typename _Elt, bool = is_void<_Elt>::value>
struct __ptr_traits_ptr_to
@@ -187,6 +191,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief Uniform interface to all pointer-like types
+ * @headerfile memory
* @ingroup pointer_abstractions
* @since C++11
*/
@@ -203,6 +208,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief Partial specialization for built-in pointers.
+ * @headerfile memory
* @ingroup pointer_abstractions
* @since C++11
*/
--
2.34.1
^ permalink raw reply [flat|nested] 12+ messages in thread
* [committed 05/12] libstdc++: Improve doxygen docs for <system_error>
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (2 preceding siblings ...)
2022-05-13 12:40 ` [committed 04/12] libstdc++: Improve doxygen docs for std::pointer_traits Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 06/12] libstdc++: Improve doxygen docs for <atomic> Jonathan Wakely
` (6 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* include/std/system_error: Improve doxygen comments.
---
libstdc++-v3/include/std/system_error | 136 ++++++++++++++++++++------
1 file changed, 107 insertions(+), 29 deletions(-)
diff --git a/libstdc++-v3/include/std/system_error b/libstdc++-v3/include/std/system_error
index dcef94e16e2..95508da73dd 100644
--- a/libstdc++-v3/include/std/system_error
+++ b/libstdc++-v3/include/std/system_error
@@ -85,13 +85,20 @@ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
/** Abstract base class for types defining a category of error codes.
*
- * An error category defines a context that give meaning to the integer
+ * An error category defines a context that gives meaning to the integer
* stored in an `error_code` or `error_condition` object. For example,
* the standard `errno` constants such a `EINVAL` and `ENOMEM` are
* associated with the "generic" category and other OS-specific error
* numbers are associated with the "system" category, but a user-defined
* category might give different meanings to the same numerical values.
*
+ * A user-defined category can override the `equivalent` member functions
+ * to define correspondence between errors in different categories.
+ * For example, a category for errors from disk I/O could consider some
+ * of its error numbers equivalent to ENOSPC and ENOENT in the generic
+ * category.
+ *
+ * @headerfile system_error
* @since C++11
*/
class error_category
@@ -104,6 +111,7 @@ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
error_category(const error_category&) = delete;
error_category& operator=(const error_category&) = delete;
+ /// A string that identifies the error category.
virtual const char*
name() const noexcept = 0;
@@ -118,6 +126,7 @@ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
_M_message(int) const;
public:
+ /// A description of the error condition corresponding to the number.
_GLIBCXX_DEFAULT_ABI_TAG
virtual string
message(int) const = 0;
@@ -131,31 +140,36 @@ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
#endif
public:
+ /// Return an error_condition corresponding to `i` in this category.
virtual error_condition
default_error_condition(int __i) const noexcept;
+ /// Test whether `cond` corresponds to `i` for this category.
virtual bool
equivalent(int __i, const error_condition& __cond) const noexcept;
+ /// Test whether `code` corresponds to `i` for this category.
virtual bool
equivalent(const error_code& __code, int __i) const noexcept;
+ /// An error_category only compares equal to itself.
bool
operator==(const error_category& __other) const noexcept
{ return this == &__other; }
+ /// Ordered comparison that defines a total order for error categories.
#if __cpp_lib_three_way_comparison
strong_ordering
operator<=>(const error_category& __rhs) const noexcept
{ return std::compare_three_way()(this, &__rhs); }
#else
- bool
- operator!=(const error_category& __other) const noexcept
- { return this != &__other; }
-
bool
operator<(const error_category& __other) const noexcept
{ return less<const error_category*>()(this, &__other); }
+
+ bool
+ operator!=(const error_category& __other) const noexcept
+ { return this != &__other; }
#endif
};
@@ -191,8 +205,8 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
* library might be represented by an HTTP response status code (e.g. 404)
* and a custom category defined by the library.
*
+ * @headerfile system_error
* @since C++11
- * @ingroup diagnostics
*/
class error_code
{
@@ -226,20 +240,25 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
operator=(_ErrorCodeEnum __e) noexcept
{ return *this = make_error_code(__e); }
+ /// The error value.
int
value() const noexcept { return _M_value; }
+ /// The error category that this error belongs to.
const error_category&
category() const noexcept { return *_M_cat; }
+ /// An `error_condition` for this error's category and value.
error_condition
default_error_condition() const noexcept;
+ /// The category's description of the value.
_GLIBCXX_DEFAULT_ABI_TAG
string
message() const
{ return category().message(value()); }
+ /// Test whether `value()` is non-zero.
explicit operator bool() const noexcept
{ return _M_value != 0; }
@@ -249,14 +268,28 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
const error_category* _M_cat;
};
- // 19.4.2.6 non-member functions
-
- /// @relates error_code @{
+ // C++11 19.5.2.5 non-member functions
+ /** Create an `error_code` representing a standard `errc` condition.
+ *
+ * The `std::errc` constants correspond to `errno` macros and so use the
+ * generic category.
+ *
+ * @relates error_code
+ * @since C++11
+ */
inline error_code
make_error_code(errc __e) noexcept
{ return error_code(static_cast<int>(__e), generic_category()); }
+ /** Ordered comparison for std::error_code.
+ *
+ * This defines a total order by comparing the categories, and then
+ * if they are equal comparing the values.
+ *
+ * @relates error_code
+ * @since C++11
+ */
#if __cpp_lib_three_way_comparison
inline strong_ordering
operator<=>(const error_code& __lhs, const error_code& __rhs) noexcept
@@ -275,13 +308,16 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
}
#endif
+ /** Write a std::error_code to an ostream.
+ *
+ * @relates error_code
+ * @since C++11
+ */
template<typename _CharT, typename _Traits>
basic_ostream<_CharT, _Traits>&
operator<<(basic_ostream<_CharT, _Traits>& __os, const error_code& __e)
{ return (__os << __e.category().name() << ':' << __e.value()); }
- /// @}
-
error_condition make_error_condition(errc) noexcept;
/** Class error_condition
@@ -293,14 +329,17 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
* An `error_condition` represents something that the program can test for,
* and subsequently take appropriate action.
*
+ * @headerfile system_error
* @since C++11
*/
class error_condition
{
public:
+ /// Initialize with a zero (no error) value and the generic category.
error_condition() noexcept
: _M_value(0), _M_cat(&generic_category()) { }
+ /// Initialize with the specified value and category.
error_condition(int __v, const error_category& __cat) noexcept
: _M_value(__v), _M_cat(&__cat) { }
@@ -309,6 +348,7 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
error_condition(_ErrorConditionEnum __e) noexcept
{ *this = make_error_condition(__e); }
+ /// Set the value and category.
void
assign(int __v, const error_category& __cat) noexcept
{
@@ -323,22 +363,28 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
operator=(_ErrorConditionEnum __e) noexcept
{ return *this = make_error_condition(__e); }
+ /// Reset the value and category to the default-constructed state.
void
clear() noexcept
{ assign(0, generic_category()); }
- // 19.4.3.4 observers
+ // C++11 19.5.3.4 observers
+
+ /// The error value.
int
value() const noexcept { return _M_value; }
+ /// The error category that this error belongs to.
const error_category&
category() const noexcept { return *_M_cat; }
+ /// The category's description of the value.
_GLIBCXX_DEFAULT_ABI_TAG
string
message() const
{ return category().message(value()); }
+ /// Test whether `value()` is non-zero.
explicit operator bool() const noexcept
{ return _M_value != 0; }
@@ -348,42 +394,75 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
const error_category* _M_cat;
};
- // 19.4.3.6 non-member functions
+ // C++11 19.5.3.5 non-member functions
- /// Create an `error_condition` representing a standard `errc` condition.
- /// @relates error_condition
+ /** Create an `error_condition` representing a standard `errc` condition.
+ *
+ * The `std::errc` constants correspond to `errno` macros and so use the
+ * generic category.
+ *
+ * @relates error_condition
+ * @since C++11
+ */
inline error_condition
make_error_condition(errc __e) noexcept
{ return error_condition(static_cast<int>(__e), generic_category()); }
- // 19.4.4 Comparison operators
+ // C++11 19.5.4 Comparison operators
- /// @relates error_code
+ /** Equality comparison for std::error_code.
+ *
+ * Returns true only if they have the same category and the same value.
+ *
+ * @relates error_condition
+ * @since C++11
+ */
inline bool
operator==(const error_code& __lhs, const error_code& __rhs) noexcept
- { return (__lhs.category() == __rhs.category()
- && __lhs.value() == __rhs.value()); }
+ {
+ return __lhs.category() == __rhs.category()
+ && __lhs.value() == __rhs.value();
+ }
- /// @relates error_code
+ /** Equality comparison for std::error_code and std::error_condition.
+ *
+ * Uses each category's `equivalent` member function to check whether
+ * the values correspond to an equivalent error in that category.
+ *
+ * @relates error_condition
+ * @since C++11
+ */
inline bool
operator==(const error_code& __lhs, const error_condition& __rhs) noexcept
{
- return (__lhs.category().equivalent(__lhs.value(), __rhs)
- || __rhs.category().equivalent(__lhs, __rhs.value()));
+ return __lhs.category().equivalent(__lhs.value(), __rhs)
+ || __rhs.category().equivalent(__lhs, __rhs.value());
}
- /// @relates error_condition
+ /** Equality comparison for std::error_condition.
+ *
+ * Returns true only if they have the same category and the same value.
+ *
+ * @relates error_condition
+ * @since C++11
+ */
inline bool
operator==(const error_condition& __lhs,
const error_condition& __rhs) noexcept
{
- return (__lhs.category() == __rhs.category()
- && __lhs.value() == __rhs.value());
+ return __lhs.category() == __rhs.category()
+ && __lhs.value() == __rhs.value();
}
+ /** Ordered comparison for std::error_condition.
+ *
+ * This defines a total order by comparing the categories, and then
+ * if they are equal comparing the values.
+ *
+ * @relates error_condition
+ * @since C++11
+ */
#if __cpp_lib_three_way_comparison
- /// Define an ordering for error_condition objects.
- /// @relates error_condition
inline strong_ordering
operator<=>(const error_condition& __lhs,
const error_condition& __rhs) noexcept
@@ -393,8 +472,6 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
return __lhs.value() <=> __rhs.value();
}
#else
- /// Define an ordering for error_condition objects.
- /// @relates error_condition
inline bool
operator<(const error_condition& __lhs,
const error_condition& __rhs) noexcept
@@ -441,6 +518,7 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
* Typically used to report errors from the operating system and other
* low-level APIs.
*
+ * @headerfile system_error
* @since C++11
* @ingroup exceptions
*/
--
2.34.1
^ permalink raw reply [flat|nested] 12+ messages in thread
* [committed 06/12] libstdc++: Improve doxygen docs for <atomic>
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (3 preceding siblings ...)
2022-05-13 12:40 ` [committed 05/12] libstdc++: Improve doxygen docs for <system_error> Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 07/12] libstdc++: Improve doxygen docs for <regex> Jonathan Wakely
` (5 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* include/std/atomic: Suppress doxygen docs for
implementation details.
* include/bits/atomic_base.h: Likewise.
* include/bits/shared_ptr_atomic.h: Use markdown. Fix grouping
so that std::atomic is not added to the pointer abstractions
group.
---
libstdc++-v3/include/bits/atomic_base.h | 41 ++++++++++++++-----
libstdc++-v3/include/bits/shared_ptr_atomic.h | 32 +++++++++------
libstdc++-v3/include/std/atomic | 11 +++--
3 files changed, 57 insertions(+), 27 deletions(-)
diff --git a/libstdc++-v3/include/bits/atomic_base.h b/libstdc++-v3/include/bits/atomic_base.h
index 5cf217dbf28..d29e4434177 100644
--- a/libstdc++-v3/include/bits/atomic_base.h
+++ b/libstdc++-v3/include/bits/atomic_base.h
@@ -86,6 +86,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
} memory_order;
#endif
+ /// @cond undocumented
enum __memory_order_modifier
{
__memory_order_mask = 0x0ffff,
@@ -93,6 +94,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
__memory_order_hle_acquire = 0x10000,
__memory_order_hle_release = 0x20000
};
+ /// @endcond
constexpr memory_order
operator|(memory_order __m, __memory_order_modifier __mod)
@@ -106,6 +108,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return memory_order(int(__m) & int(__mod));
}
+ /// @cond undocumented
+
// Drop release ordering as per [atomics.types.operations.req]/21
constexpr memory_order
__cmpexch_failure_order2(memory_order __m) noexcept
@@ -128,6 +132,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
&& (__m & __memory_order_mask) != memory_order_acq_rel;
}
+ // Base types for atomics.
+ template<typename _IntTp>
+ struct __atomic_base;
+
+ /// @endcond
+
_GLIBCXX_ALWAYS_INLINE void
atomic_thread_fence(memory_order __m) noexcept
{ __atomic_thread_fence(int(__m)); }
@@ -145,17 +155,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return __ret;
}
- // Base types for atomics.
- template<typename _IntTp>
- struct __atomic_base;
-
-#if __cplusplus <= 201703L
-# define _GLIBCXX20_INIT(I)
-#else
+#if __cplusplus >= 202002L
# define __cpp_lib_atomic_value_initialization 201911L
-# define _GLIBCXX20_INIT(I) = I
#endif
+/// @cond undocumented
+#if __cpp_lib_atomic_value_initialization
+# define _GLIBCXX20_INIT(I) = I
+#else
+# define _GLIBCXX20_INIT(I)
+#endif
+/// @endcond
+
#define ATOMIC_VAR_INIT(_VI) { _VI }
template<typename _Tp>
@@ -171,8 +182,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
typedef unsigned char __atomic_flag_data_type;
#endif
- /**
- * @brief Base type for atomic_flag.
+ /// @cond undocumented
+
+ /*
+ * Base type for atomic_flag.
*
* Base type is POD with data, allowing atomic_flag to derive from
* it and meet the standard layout type requirement. In addition to
@@ -190,6 +203,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_GLIBCXX_END_EXTERN_C
+ /// @endcond
+
#define ATOMIC_FLAG_INIT { 0 }
/// atomic_flag
@@ -295,6 +310,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return __i ? __GCC_ATOMIC_TEST_AND_SET_TRUEVAL : 0; }
};
+ /// @cond undocumented
/// Base class for atomic integrals.
//
@@ -936,7 +952,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return __atomic_fetch_sub(&_M_p, _M_type_size(__d), int(__m)); }
};
+ /// @endcond
+
#if __cplusplus > 201703L
+ /// @cond undocumented
+
// Implementation details of atomic_ref and atomic<floating-point>.
namespace __atomic_impl
{
@@ -1936,6 +1956,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Tp** _M_ptr;
};
+ /// @endcond
#endif // C++2a
/// @} group atomics
diff --git a/libstdc++-v3/include/bits/shared_ptr_atomic.h b/libstdc++-v3/include/bits/shared_ptr_atomic.h
index ff86432f0b4..d4bd712fc7d 100644
--- a/libstdc++-v3/include/bits/shared_ptr_atomic.h
+++ b/libstdc++-v3/include/bits/shared_ptr_atomic.h
@@ -38,9 +38,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @addtogroup pointer_abstractions
+ * @relates shared_ptr
* @{
*/
- /// @relates shared_ptr @{
/// @cond undocumented
@@ -94,8 +94,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __p A non-null pointer to a shared_ptr object.
* @return @c *__p
*
- * The memory order shall not be @c memory_order_release or
- * @c memory_order_acq_rel.
+ * The memory order shall not be `memory_order_release` or
+ * `memory_order_acq_rel`.
* @{
*/
template<typename _Tp>
@@ -130,8 +130,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __p A non-null pointer to a shared_ptr object.
* @param __r The value to store.
*
- * The memory order shall not be @c memory_order_acquire or
- * @c memory_order_acq_rel.
+ * The memory order shall not be `memory_order_acquire` or
+ * `memory_order_acq_rel`.
* @{
*/
template<typename _Tp>
@@ -167,8 +167,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief Atomic exchange for shared_ptr objects.
* @param __p A non-null pointer to a shared_ptr object.
- * @param __r New value to store in @c *__p.
- * @return The original value of @c *__p
+ * @param __r New value to store in `*__p`.
+ * @return The original value of `*__p`
* @{
*/
template<typename _Tp>
@@ -214,10 +214,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __p A non-null pointer to a shared_ptr object.
* @param __v A non-null pointer to a shared_ptr object.
* @param __w A non-null pointer to a shared_ptr object.
- * @return True if @c *__p was equivalent to @c *__v, false otherwise.
+ * @return True if `*__p` was equivalent to `*__v`, false otherwise.
*
- * The memory order for failure shall not be @c memory_order_release or
- * @c memory_order_acq_rel, or stronger than the memory order for success.
+ * The memory order for failure shall not be `memory_order_release` or
+ * `memory_order_acq_rel`.
* @{
*/
template<typename _Tp>
@@ -327,11 +327,19 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
/// @}
+ /// @} group pointer_abstractions
+
#if __cplusplus >= 202002L
# define __cpp_lib_atomic_shared_ptr 201711L
template<typename _Tp>
class atomic;
+ /**
+ * @addtogroup pointer_abstractions
+ * @relates shared_ptr
+ * @{
+ */
+
template<typename _Up>
static constexpr bool __is_shared_ptr = false;
template<typename _Up>
@@ -788,10 +796,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
private:
_Sp_atomic<weak_ptr<_Tp>> _M_impl;
};
-#endif // C++20
-
- /// @} relates shared_ptr
/// @} group pointer_abstractions
+#endif // C++20
_GLIBCXX_END_NAMESPACE_VERSION
} // namespace
diff --git a/libstdc++-v3/include/std/atomic b/libstdc++-v3/include/std/atomic
index d819b6bf41e..1c6acfa36d0 100644
--- a/libstdc++-v3/include/std/atomic
+++ b/libstdc++-v3/include/std/atomic
@@ -181,11 +181,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif // __cpp_lib_atomic_wait
};
-#if __cplusplus <= 201703L
-# define _GLIBCXX20_INIT(I)
-#else
+/// @cond undocumented
+#if __cpp_lib_atomic_value_initialization
# define _GLIBCXX20_INIT(I) = I
+#else
+# define _GLIBCXX20_INIT(I)
#endif
+/// @endcond
/**
* @brief Generic atomic type, primary class template.
@@ -1241,11 +1243,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
atomic_flag_clear(volatile atomic_flag* __a) noexcept
{ atomic_flag_clear_explicit(__a, memory_order_seq_cst); }
-
+ /// @cond undocumented
template<typename _Tp>
using __atomic_val_t = typename atomic<_Tp>::value_type;
template<typename _Tp>
using __atomic_diff_t = typename atomic<_Tp>::difference_type;
+ /// @endcond
// [atomics.nonmembers] Non-member functions.
// Function templates generally applicable to atomic types.
--
2.34.1
^ permalink raw reply [flat|nested] 12+ messages in thread
* [committed 07/12] libstdc++: Improve doxygen docs for <regex>
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (4 preceding siblings ...)
2022-05-13 12:40 ` [committed 06/12] libstdc++: Improve doxygen docs for <atomic> Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 08/12] libstdc++: Improve doxygen docs for std::allocator Jonathan Wakely
` (4 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
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
^ permalink raw reply [flat|nested] 12+ messages in thread
* [committed 08/12] libstdc++: Improve doxygen docs for std::allocator
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (5 preceding siblings ...)
2022-05-13 12:40 ` [committed 07/12] libstdc++: Improve doxygen docs for <regex> Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 09/12] libstdc++: Improve doxygen docs for algorithms and more Jonathan Wakely
` (3 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* doc/doxygen/user.cfg.in (PREDEFINED): Define __allocator_base
so that Doxygen shows the right base-class for std::allocator.
* include/bits/alloc_traits.h: Improve doxygen docs.
* include/bits/allocator.h: Likewise.
* include/bits/new_allocator.h: Likewise.
* include/ext/new_allocator.h: Likewise.
---
libstdc++-v3/doc/doxygen/user.cfg.in | 1 +
libstdc++-v3/include/bits/alloc_traits.h | 5 +++++
libstdc++-v3/include/bits/allocator.h | 15 ++++++++++++++-
libstdc++-v3/include/bits/new_allocator.h | 19 +++++++++++++------
libstdc++-v3/include/ext/new_allocator.h | 12 +++++++++---
5 files changed, 42 insertions(+), 10 deletions(-)
diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index 02ce290d3ad..cfda7ab13c4 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -2405,6 +2405,7 @@ PREDEFINED = __cplusplus=202002L \
_GLIBCXX_HAVE_IS_CONSTANT_EVALUATED \
_GLIBCXX_HAVE_BUILTIN_LAUNDER \
"_GLIBCXX_DOXYGEN_ONLY(X)=X " \
+ __allocator_base=std::__new_allocator \
# 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/alloc_traits.h b/libstdc++-v3/include/bits/alloc_traits.h
index a4d06d3fc7a..f9ca37fd7d6 100644
--- a/libstdc++-v3/include/bits/alloc_traits.h
+++ b/libstdc++-v3/include/bits/alloc_traits.h
@@ -661,6 +661,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return __rhs; }
};
+ /// @cond undocumented
#if __cplusplus < 201703L
template<typename _Alloc>
inline void
@@ -818,8 +819,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
__a.deallocate(__a.allocate(1u), 1u);
};
#endif
+ /// @endcond
#endif // C++11
+ /// @cond undocumented
+
/**
* Destroy a range of objects using the supplied allocator. For
* non-default allocators we do not optimize away invocation of
@@ -849,6 +853,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{
_Destroy(__first, __last);
}
+ /// @endcond
_GLIBCXX_END_NAMESPACE_VERSION
} // namespace std
diff --git a/libstdc++-v3/include/bits/allocator.h b/libstdc++-v3/include/bits/allocator.h
index f7770165273..ee1121b080a 100644
--- a/libstdc++-v3/include/bits/allocator.h
+++ b/libstdc++-v3/include/bits/allocator.h
@@ -67,7 +67,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// explicit specialization, with the historical ABI properties, but with
// the same members that are present in the primary template.
- /// allocator<void> specialization.
+ /** std::allocator<void> specialization.
+ *
+ * @headerfile memory
+ */
template<>
class allocator<void>
{
@@ -119,6 +122,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* for further details.
*
* @tparam _Tp Type of allocated object.
+ *
+ * @headerfile memory
*/
template<typename _Tp>
class allocator : public __allocator_base<_Tp>
@@ -209,6 +214,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// Inherit everything else.
};
+ /** Equality comparison for std::allocator objects
+ *
+ * @return true, for all std::allocator objects.
+ * @relates std::allocator
+ */
template<typename _T1, typename _T2>
inline _GLIBCXX20_CONSTEXPR bool
operator==(const allocator<_T1>&, const allocator<_T2>&)
@@ -223,6 +233,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return false; }
#endif
+ /// @cond undocumented
+
// Invalid allocator<cv T> partial specializations.
// allocator_traits::rebind_alloc can be used to form a valid allocator type.
template<typename _Tp>
@@ -325,6 +337,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
};
#endif
+ /// @endcond
_GLIBCXX_END_NAMESPACE_VERSION
} // namespace std
diff --git a/libstdc++-v3/include/bits/new_allocator.h b/libstdc++-v3/include/bits/new_allocator.h
index 20ef20fe118..1a5bc51b956 100644
--- a/libstdc++-v3/include/bits/new_allocator.h
+++ b/libstdc++-v3/include/bits/new_allocator.h
@@ -43,14 +43,21 @@ namespace std _GLIBCXX_VISIBILITY(default)
_GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
- * @brief An allocator that uses global new, as per C++03 [20.4.1].
- * @ingroup allocators
+ * @brief An allocator that uses global `new`, as per C++03 [20.4.1].
+ * @ingroup allocators
*
- * This is precisely the allocator defined in the C++ Standard.
- * - all allocation calls operator new
- * - all deallocation calls operator delete
+ * This is precisely the allocator defined in the C++ Standard.
+ * - all allocation calls `operator new`
+ * - all deallocation calls `operator delete`
*
- * @tparam _Tp Type of allocated object.
+ * This is the default base-class implementation of `std::allocator`,
+ * and is also the base-class of the `__gnu_cxx::new_allocator` extension.
+ * You should use either `std::allocator` or `__gnu_cxx::new_allocator`
+ * instead of using this directly.
+ *
+ * @tparam _Tp Type of allocated object.
+ *
+ * @headerfile memory
*/
template<typename _Tp>
class __new_allocator
diff --git a/libstdc++-v3/include/ext/new_allocator.h b/libstdc++-v3/include/ext/new_allocator.h
index b8f5fcccccc..96e6523977a 100644
--- a/libstdc++-v3/include/ext/new_allocator.h
+++ b/libstdc++-v3/include/ext/new_allocator.h
@@ -36,14 +36,20 @@ namespace __gnu_cxx _GLIBCXX_VISIBILITY(default)
_GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
- * @brief An allocator that uses global new, as per C++03 [20.4.1].
+ * @brief An allocator that uses global `new`, as per C++03 [20.4.1].
* @ingroup allocators
*
* This is precisely the allocator defined in the C++ Standard.
- * - all allocation calls operator new
- * - all deallocation calls operator delete
+ * - all allocation calls `operator new`
+ * - all deallocation calls `operator delete`
+ *
+ * This is a non-standard extension that can be used to guarantee
+ * allocation from `new` even if the library has been configured to
+ * use a different implementation for `std::allocator`.
*
* @tparam _Tp Type of allocated object.
+ *
+ * @headerfile ext/new_allocator.h
*/
template<typename _Tp>
class new_allocator : public std::__new_allocator<_Tp>
--
2.34.1
^ permalink raw reply [flat|nested] 12+ messages in thread
* [committed 09/12] libstdc++: Improve doxygen docs for algorithms and more
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (6 preceding siblings ...)
2022-05-13 12:40 ` [committed 08/12] libstdc++: Improve doxygen docs for std::allocator Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 10/12] libstdc++: Improve doxygen docs for <thread> and <future> Jonathan Wakely
` (2 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* include/bits/ostream_insert.h: Mark helper functions as
undocumented by Doxygen.
* include/bits/stl_algo.h: Use markdown for formatting and mark
helper functions as undocumented.
* include/bits/stl_numeric.h: Likewise.
* include/bits/stl_pair.h (pair): Add @headerfile.
---
libstdc++-v3/include/bits/ostream_insert.h | 4 +
libstdc++-v3/include/bits/stl_algo.h | 198 +++++++++++----------
libstdc++-v3/include/bits/stl_numeric.h | 10 +-
libstdc++-v3/include/bits/stl_pair.h | 4 +
4 files changed, 112 insertions(+), 104 deletions(-)
diff --git a/libstdc++-v3/include/bits/ostream_insert.h b/libstdc++-v3/include/bits/ostream_insert.h
index 9442ea130d3..f236353b2a6 100644
--- a/libstdc++-v3/include/bits/ostream_insert.h
+++ b/libstdc++-v3/include/bits/ostream_insert.h
@@ -40,6 +40,8 @@ namespace std _GLIBCXX_VISIBILITY(default)
{
_GLIBCXX_BEGIN_NAMESPACE_VERSION
+ /// @cond undocumented
+
template<typename _CharT, typename _Traits>
inline void
__ostream_write(basic_ostream<_CharT, _Traits>& __out,
@@ -124,6 +126,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif
#endif
+ /// @endcond
+
_GLIBCXX_END_NAMESPACE_VERSION
} // namespace std
diff --git a/libstdc++-v3/include/bits/stl_algo.h b/libstdc++-v3/include/bits/stl_algo.h
index 6619ff7bf1d..1d8ed4e5fa8 100644
--- a/libstdc++-v3/include/bits/stl_algo.h
+++ b/libstdc++-v3/include/bits/stl_algo.h
@@ -1617,6 +1617,8 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
__gnu_cxx::__ops::__pred_iter(__pred));
}
+ /// @cond undocumented
+
/// This is a helper function for the sort routines.
template<typename _RandomAccessIterator, typename _Compare>
_GLIBCXX20_CONSTEXPR
@@ -1671,6 +1673,8 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
return __result_real_last;
}
+ /// @endcond
+
/**
* @brief Copy the smallest elements of a sequence.
* @ingroup sorting_algorithms
@@ -1680,14 +1684,14 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
* @param __result_last Another random-access iterator.
* @return An iterator indicating the end of the resulting sequence.
*
- * Copies and sorts the smallest N values from the range @p [__first,__last)
- * to the range beginning at @p __result_first, where the number of
- * elements to be copied, @p N, is the smaller of @p (__last-__first) and
- * @p (__result_last-__result_first).
- * After the sort if @e i and @e j are iterators in the range
- * @p [__result_first,__result_first+N) such that i precedes j then
- * *j<*i is false.
- * The value returned is @p __result_first+N.
+ * Copies and sorts the smallest `N` values from the range
+ * `[__first, __last)` to the range beginning at `__result_first`, where
+ * the number of elements to be copied, `N`, is the smaller of
+ * `(__last - __first)` and `(__result_last - __result_first)`.
+ * After the sort if `i` and `j` are iterators in the range
+ * `[__result_first,__result_first + N)` such that `i` precedes `j` then
+ * `*j < *i` is false.
+ * The value returned is `__result_first + N`.
*/
template<typename _InputIterator, typename _RandomAccessIterator>
_GLIBCXX20_CONSTEXPR
@@ -1730,14 +1734,14 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
* @param __comp A comparison functor.
* @return An iterator indicating the end of the resulting sequence.
*
- * Copies and sorts the smallest N values from the range @p [__first,__last)
- * to the range beginning at @p result_first, where the number of
- * elements to be copied, @p N, is the smaller of @p (__last-__first) and
- * @p (__result_last-__result_first).
- * After the sort if @e i and @e j are iterators in the range
- * @p [__result_first,__result_first+N) such that i precedes j then
- * @p __comp(*j,*i) is false.
- * The value returned is @p __result_first+N.
+ * Copies and sorts the smallest `N` values from the range
+ * `[__first, __last)` to the range beginning at `result_first`, where
+ * the number of elements to be copied, `N`, is the smaller of
+ * `(__last - __first)` and `(__result_last - __result_first)`.
+ * After the sort if `i` and `j` are iterators in the range
+ * `[__result_first, __result_first + N)` such that `i` precedes `j` then
+ * `__comp(*j, *i)` is false.
+ * The value returned is `__result_first + N`.
*/
template<typename _InputIterator, typename _RandomAccessIterator,
typename _Compare>
@@ -1774,6 +1778,8 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
__gnu_cxx::__ops::__iter_comp_iter(__comp));
}
+ /// @cond undocumented
+
/// This is a helper function for the sort routine.
template<typename _RandomAccessIterator, typename _Compare>
_GLIBCXX20_CONSTEXPR
@@ -1967,21 +1973,22 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
std::__insertion_sort(__first, __last, __comp);
}
+ /// @endcond
+
// nth_element
// lower_bound moved to stl_algobase.h
/**
- * @brief Finds the first position in which @p __val could be inserted
+ * @brief Finds the first position in which `__val` could be inserted
* without changing the ordering.
* @ingroup binary_search_algorithms
- * @param __first An iterator.
- * @param __last Another iterator.
+ * @param __first An iterator to the start of a sorted range.
+ * @param __last A past-the-end iterator for the sorted range.
* @param __val The search term.
* @param __comp A functor to use for comparisons.
- * @return An iterator pointing to the first element <em>not less
- * than</em> @p __val, or end() if every element is less
- * than @p __val.
+ * @return An iterator pointing to the first element _not less than_
+ * `__val`, or `end()` if every element is less than `__val`.
* @ingroup binary_search_algorithms
*
* The comparison function should have the same effects on ordering as
@@ -4313,8 +4320,8 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __new_value The replacement value.
* @return replace() returns no value.
*
- * For each iterator @c i in the range @p [__first,__last) if @c *i ==
- * @p __old_value then the assignment @c *i = @p __new_value is performed.
+ * For each iterator `i` in the range `[__first,__last)` if
+ * `*i == __old_value` then the assignment `*i = __new_value` is performed.
*/
template<typename _ForwardIterator, typename _Tp>
_GLIBCXX20_CONSTEXPR
@@ -4346,8 +4353,8 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __new_value The replacement value.
* @return replace_if() returns no value.
*
- * For each iterator @c i in the range @p [__first,__last) if @p __pred(*i)
- * is true then the assignment @c *i = @p __new_value is performed.
+ * For each iterator `i` in the range `[__first,__last)` if `__pred(*i)`
+ * is true then the assignment `*i = __new_value` is performed.
*/
template<typename _ForwardIterator, typename _Predicate, typename _Tp>
_GLIBCXX20_CONSTEXPR
@@ -4375,12 +4382,11 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @ingroup mutating_algorithms
* @param __first A forward iterator.
* @param __last A forward iterator.
- * @param __gen A function object taking no arguments and returning
- * std::iterator_traits<_ForwardIterator>::value_type
+ * @param __gen A function object callable with no arguments.
* @return generate() returns no value.
*
- * Performs the assignment @c *i = @p __gen() for each @c i in the range
- * @p [__first,__last).
+ * Performs the assignment `*i = __gen()` for each `i` in the range
+ * `[__first, __last)`.
*/
template<typename _ForwardIterator, typename _Generator>
_GLIBCXX20_CONSTEXPR
@@ -4404,14 +4410,13 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @ingroup mutating_algorithms
* @param __first A forward iterator.
* @param __n The length of the sequence.
- * @param __gen A function object taking no arguments and returning
- * std::iterator_traits<_ForwardIterator>::value_type
- * @return The end of the sequence, @p __first+__n
+ * @param __gen A function object callable with no arguments.
+ * @return The end of the sequence, i.e., `__first + __n`
*
- * Performs the assignment @c *i = @p __gen() for each @c i in the range
- * @p [__first,__first+__n).
+ * Performs the assignment `*i = __gen()` for each `i` in the range
+ * `[__first, __first + __n)`.
*
- * If @p __n is negative, the function does nothing and returns @p __first.
+ * If `__n` is negative, the function does nothing and returns `__first`.
*/
// _GLIBCXX_RESOLVE_LIB_DEFECTS
// DR 865. More algorithms that throw away information
@@ -4441,19 +4446,16 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __result An output iterator.
* @return An iterator designating the end of the resulting sequence.
*
- * Copies each element in the range @p [__first,__last) to the range
- * beginning at @p __result, except that only the first element is copied
+ * Copies each element in the range `[__first, __last)` to the range
+ * beginning at `__result`, except that only the first element is copied
* from groups of consecutive elements that compare equal.
- * unique_copy() is stable, so the relative order of elements that are
+ * `unique_copy()` is stable, so the relative order of elements that are
* copied is unchanged.
- *
- * _GLIBCXX_RESOLVE_LIB_DEFECTS
- * DR 241. Does unique_copy() require CopyConstructible and Assignable?
- *
- * _GLIBCXX_RESOLVE_LIB_DEFECTS
- * DR 538. 241 again: Does unique_copy() require CopyConstructible and
- * Assignable?
- */
+ */
+ // _GLIBCXX_RESOLVE_LIB_DEFECTS
+ // DR 241. Does unique_copy() require CopyConstructible and Assignable?
+ // DR 538. 241 again: Does unique_copy() require CopyConstructible and
+ // Assignable?
template<typename _InputIterator, typename _OutputIterator>
_GLIBCXX20_CONSTEXPR
inline _OutputIterator
@@ -4485,16 +4487,15 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __binary_pred A binary predicate.
* @return An iterator designating the end of the resulting sequence.
*
- * Copies each element in the range @p [__first,__last) to the range
- * beginning at @p __result, except that only the first element is copied
- * from groups of consecutive elements for which @p __binary_pred returns
+ * Copies each element in the range `[__first, __last)` to the range
+ * beginning at `__result`, except that only the first element is copied
+ * from groups of consecutive elements for which `__binary_pred` returns
* true.
- * unique_copy() is stable, so the relative order of elements that are
+ * `unique_copy()` is stable, so the relative order of elements that are
* copied is unchanged.
- *
- * _GLIBCXX_RESOLVE_LIB_DEFECTS
- * DR 241. Does unique_copy() require CopyConstructible and Assignable?
- */
+ */
+ // _GLIBCXX_RESOLVE_LIB_DEFECTS
+ // DR 241. Does unique_copy() require CopyConstructible and Assignable?
template<typename _InputIterator, typename _OutputIterator,
typename _BinaryPredicate>
_GLIBCXX20_CONSTEXPR
@@ -4526,7 +4527,7 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __last A forward iterator.
* @return Nothing.
*
- * Reorder the elements in the range @p [__first,__last) using a random
+ * Reorder the elements in the range `[__first, __last)` using a random
* distribution, so that every possible ordering of the sequence is
* equally likely.
*
@@ -4565,10 +4566,10 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __rand The RNG functor or function.
* @return Nothing.
*
- * Reorders the elements in the range @p [__first,__last) using @p __rand to
- * provide a random distribution. Calling @p __rand(N) for a positive
- * integer @p N should return a randomly chosen integer from the
- * range [0,N).
+ * Reorders the elements in the range `[__first, __last)` using `__rand`
+ * to provide a random distribution. Calling `__rand(N)` for a positive
+ * integer `N` should return a randomly chosen integer from the
+ * range `[0, N)`.
*
* @deprecated
* Since C++14 `std::random_shuffle` is not part of the C++ standard.
@@ -4607,13 +4608,13 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __first A forward iterator.
* @param __last A forward iterator.
* @param __pred A predicate functor.
- * @return An iterator @p middle such that @p __pred(i) is true for each
- * iterator @p i in the range @p [__first,middle) and false for each @p i
- * in the range @p [middle,__last).
+ * @return An iterator `middle` such that `__pred(i)` is true for each
+ * iterator `i` in the range `[__first, middle)` and false for each `i`
+ * in the range `[middle, __last)`.
*
- * @p __pred must not modify its operand. @p partition() does not preserve
+ * `__pred` must not modify its operand. `partition()` does not preserve
* the relative ordering of elements in each group, use
- * @p stable_partition() if this is needed.
+ * `stable_partition()` if this is needed.
*/
template<typename _ForwardIterator, typename _Predicate>
_GLIBCXX20_CONSTEXPR
@@ -4641,13 +4642,14 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __last Another iterator.
* @return Nothing.
*
- * Sorts the smallest @p (__middle-__first) elements in the range
- * @p [first,last) and moves them to the range @p [__first,__middle). The
- * order of the remaining elements in the range @p [__middle,__last) is
- * undefined.
- * After the sort if @e i and @e j are iterators in the range
- * @p [__first,__middle) such that i precedes j and @e k is an iterator in
- * the range @p [__middle,__last) then *j<*i and *k<*i are both false.
+ * Sorts the smallest `(__middle - __first)` elements in the range
+ * `[first, last)` and moves them to the range `[__first, __middle)`. The
+ * order of the remaining elements in the range `[__middle, __last)` is
+ * unspecified.
+ * After the sort if `i` and `j` are iterators in the range
+ * `[__first, __middle)` such that `i` precedes `j` and `k` is an iterator
+ * in the range `[__middle, __last)` then `*j < *i` and `*k < *i` are
+ * both false.
*/
template<typename _RandomAccessIterator>
_GLIBCXX20_CONSTEXPR
@@ -4679,14 +4681,14 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __comp A comparison functor.
* @return Nothing.
*
- * Sorts the smallest @p (__middle-__first) elements in the range
- * @p [__first,__last) and moves them to the range @p [__first,__middle). The
- * order of the remaining elements in the range @p [__middle,__last) is
- * undefined.
- * After the sort if @e i and @e j are iterators in the range
- * @p [__first,__middle) such that i precedes j and @e k is an iterator in
- * the range @p [__middle,__last) then @p *__comp(j,*i) and @p __comp(*k,*i)
- * are both false.
+ * Sorts the smallest `(__middle - __first)` elements in the range
+ * `[__first, __last)` and moves them to the range `[__first, __middle)`.
+ * The order of the remaining elements in the range `[__middle, __last)` is
+ * unspecified.
+ * After the sort if `i` and `j` are iterators in the range
+ * `[__first, __middle)` such that `i` precedes `j` and `k` is an iterator
+ * in the range `[__middle, __last)` then `*__comp(j, *i)` and
+ * `__comp(*k, *i)` are both false.
*/
template<typename _RandomAccessIterator, typename _Compare>
_GLIBCXX20_CONSTEXPR
@@ -4718,12 +4720,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __last Another iterator.
* @return Nothing.
*
- * Rearranges the elements in the range @p [__first,__last) so that @p *__nth
+ * Rearranges the elements in the range `[__first, __last)` so that `*__nth`
* is the same element that would have been in that position had the
- * whole sequence been sorted. The elements either side of @p *__nth are
- * not completely sorted, but for any iterator @e i in the range
- * @p [__first,__nth) and any iterator @e j in the range @p [__nth,__last) it
- * holds that *j < *i is false.
+ * whole sequence been sorted. The elements either side of `*__nth` are
+ * not completely sorted, but for any iterator `i` in the range
+ * `[__first, __nth)` and any iterator `j` in the range `[__nth, __last)` it
+ * holds that `*j < *i` is false.
*/
template<typename _RandomAccessIterator>
_GLIBCXX20_CONSTEXPR
@@ -4758,12 +4760,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __comp A comparison functor.
* @return Nothing.
*
- * Rearranges the elements in the range @p [__first,__last) so that @p *__nth
+ * Rearranges the elements in the range `[__first, __last)` so that `*__nth`
* is the same element that would have been in that position had the
- * whole sequence been sorted. The elements either side of @p *__nth are
- * not completely sorted, but for any iterator @e i in the range
- * @p [__first,__nth) and any iterator @e j in the range @p [__nth,__last) it
- * holds that @p __comp(*j,*i) is false.
+ * whole sequence been sorted. The elements either side of `*__nth` are
+ * not completely sorted, but for any iterator `i` in the range
+ * `[__first, __nth)` and any iterator `j` in the range `[__nth, __last)`
+ * it holds that `__comp(*j, *i)` is false.
*/
template<typename _RandomAccessIterator, typename _Compare>
_GLIBCXX20_CONSTEXPR
@@ -4796,12 +4798,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __last Another iterator.
* @return Nothing.
*
- * Sorts the elements in the range @p [__first,__last) in ascending order,
- * such that for each iterator @e i in the range @p [__first,__last-1),
- * *(i+1)<*i is false.
+ * Sorts the elements in the range `[__first, __last)` in ascending order,
+ * such that for each iterator `i` in the range `[__first, __last - 1)`,
+ * `*(i+1) < *i` is false.
*
* The relative ordering of equivalent elements is not preserved, use
- * @p stable_sort() if this is needed.
+ * `stable_sort()` if this is needed.
*/
template<typename _RandomAccessIterator>
_GLIBCXX20_CONSTEXPR
@@ -4827,12 +4829,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __comp A comparison functor.
* @return Nothing.
*
- * Sorts the elements in the range @p [__first,__last) in ascending order,
- * such that @p __comp(*(i+1),*i) is false for every iterator @e i in the
- * range @p [__first,__last-1).
+ * Sorts the elements in the range `[__first, __last)` in ascending order,
+ * such that `__comp(*(i+1), *i)` is false for every iterator `i` in the
+ * range `[__first, __last - 1)`.
*
* The relative ordering of equivalent elements is not preserved, use
- * @p stable_sort() if this is needed.
+ * `stable_sort()` if this is needed.
*/
template<typename _RandomAccessIterator, typename _Compare>
_GLIBCXX20_CONSTEXPR
diff --git a/libstdc++-v3/include/bits/stl_numeric.h b/libstdc++-v3/include/bits/stl_numeric.h
index ea017d41e76..f71236cab5d 100644
--- a/libstdc++-v3/include/bits/stl_numeric.h
+++ b/libstdc++-v3/include/bits/stl_numeric.h
@@ -328,10 +328,9 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __last End of input range.
* @param __result Output sums.
* @return Iterator pointing just beyond the values written to result.
- *
- * _GLIBCXX_RESOLVE_LIB_DEFECTS
- * DR 539. partial_sum and adjacent_difference should mention requirements
*/
+ // _GLIBCXX_RESOLVE_LIB_DEFECTS
+ // DR 539. partial_sum and adjacent_difference should mention requirements
template<typename _InputIterator, typename _OutputIterator>
_GLIBCXX20_CONSTEXPR
_OutputIterator
@@ -371,10 +370,9 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __result Output sum.
* @param __binary_op Function object.
* @return Iterator pointing just beyond the values written to result.
- *
- * _GLIBCXX_RESOLVE_LIB_DEFECTS
- * DR 539. partial_sum and adjacent_difference should mention requirements
*/
+ // _GLIBCXX_RESOLVE_LIB_DEFECTS
+ // DR 539. partial_sum and adjacent_difference should mention requirements
template<typename _InputIterator, typename _OutputIterator,
typename _BinaryOperation>
_GLIBCXX20_CONSTEXPR
diff --git a/libstdc++-v3/include/bits/stl_pair.h b/libstdc++-v3/include/bits/stl_pair.h
index 0eb78345ca4..831e770d54b 100644
--- a/libstdc++-v3/include/bits/stl_pair.h
+++ b/libstdc++-v3/include/bits/stl_pair.h
@@ -180,6 +180,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @tparam _T2 Type of second object.
*
* <https://gcc.gnu.org/onlinedocs/libstdc++/manual/utilities.html>
+ *
+ * @headerfile utility
*/
template<typename _T1, typename _T2>
struct pair
@@ -757,9 +759,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#if __cplusplus >= 201103L
// Various functions which give std::pair a tuple-like interface.
+ /// @cond undocumented
template<typename _T1, typename _T2>
struct __is_tuple_like_impl<pair<_T1, _T2>> : true_type
{ };
+ /// @endcond
/// Partial specialization for std::pair
template<class _Tp1, class _Tp2>
--
2.34.1
^ permalink raw reply [flat|nested] 12+ messages in thread
* [committed 10/12] libstdc++: Improve doxygen docs for <thread> and <future>
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (7 preceding siblings ...)
2022-05-13 12:40 ` [committed 09/12] libstdc++: Improve doxygen docs for algorithms and more Jonathan Wakely
@ 2022-05-13 12:40 ` 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
10 siblings, 0 replies; 12+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* include/bits/std_thread.h (thread, thread::id): Improve
doxygen docs.
* include/std/future: Likewise.
* include/std/thread (jthread): Likewise.
---
libstdc++-v3/include/bits/std_thread.h | 33 ++++++++++++++++++++++----
libstdc++-v3/include/std/future | 29 ++++++++++++++++++----
libstdc++-v3/include/std/thread | 21 +++++++++++++++-
3 files changed, 73 insertions(+), 10 deletions(-)
diff --git a/libstdc++-v3/include/bits/std_thread.h b/libstdc++-v3/include/bits/std_thread.h
index dd625de3bc3..f67bc114591 100644
--- a/libstdc++-v3/include/bits/std_thread.h
+++ b/libstdc++-v3/include/bits/std_thread.h
@@ -57,7 +57,24 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @{
*/
- /// thread
+ /** A std::thread represents a new thread of execution.
+ *
+ * The default constructor creates an object that does not own a thread.
+ * The `thread(F&&, Args&&...)` constructor invokes a callable in a new
+ * thread, and owns that new thread. A `std::thread` that owns a thread
+ * is *joinable*. Joining a thread waits for it to finish executing,
+ * which happens when the callable running in that thread returns.
+ *
+ * A `std::thread` cannot be copied, but can be moved. Moving a joinable
+ * object transfers ownership of its thread to another object.
+ *
+ * A joinable `std::thread` must be explicitly joined (or detached) before
+ * it is destroyed or assigned to. Attempting to destroy a joinable thread
+ * will terminate the whole process.
+ *
+ * @headerfile thread
+ * @since C++11
+ */
class thread
{
public:
@@ -76,7 +93,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
using native_handle_type = int;
#endif
- /// thread::id
+ /** A std::thread::id is a unique identifier for a thread.
+ *
+ * @headerfile thread
+ * @since C++11
+ */
class id
{
native_handle_type _M_thread;
@@ -261,8 +282,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
};
public:
+ /// @cond undocumented
template<typename... _Tp>
using _Call_wrapper = _Invoker<tuple<typename decay<_Tp>::type...>>;
+ /// @endcond
#endif // _GLIBCXX_HAS_GTHREADS
};
@@ -272,10 +295,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
inline unsigned int thread::hardware_concurrency() noexcept { return 0; }
#endif
+ /// @relates std::thread
inline void
swap(thread& __x, thread& __y) noexcept
{ __x.swap(__y); }
+ /// @relates std::thread::id
inline bool
operator==(thread::id __x, thread::id __y) noexcept
{
@@ -301,7 +326,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
namespace this_thread
{
- /// this_thread::get_id
+ /// The unique identifier of the current thread.
inline thread::id
get_id() noexcept
{
@@ -314,7 +339,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif
}
- /// this_thread::yield
+ /// Allow the implementation to schedule a different thread.
inline void
yield() noexcept
{
diff --git a/libstdc++-v3/include/std/future b/libstdc++-v3/include/std/future
index a9268cade91..3d5d793a08e 100644
--- a/libstdc++-v3/include/std/future
+++ b/libstdc++-v3/include/std/future
@@ -58,7 +58,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @defgroup futures Futures
* @ingroup concurrency
*
- * Classes for futures support.
+ * Futures and promises provide support for retrieving the result from
+ * an asynchronous function, e.g. one that is running in another thread.
+ * A `std::future` represents an asynchronous result that will become
+ * ready at some later time. A consumer can wait on a future until the
+ * result is ready to be accessed.
+ *
+ * @since C++11
* @{
*/
@@ -71,7 +77,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
broken_promise
};
- /// Specialization.
+ /// Specialization that allows `future_errc` to convert to `error_code`.
template<>
struct is_error_code_enum<future_errc> : public true_type { };
@@ -79,12 +85,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
const error_category&
future_category() noexcept;
- /// Overload for make_error_code.
+ /// Overload of make_error_code for `future_errc`.
inline error_code
make_error_code(future_errc __errc) noexcept
{ return error_code(static_cast<int>(__errc), future_category()); }
- /// Overload for make_error_condition.
+ /// Overload of make_error_condition for `future_errc`.
inline error_condition
make_error_condition(future_errc __errc) noexcept
{ return error_condition(static_cast<int>(__errc), future_category()); }
@@ -92,6 +98,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief Exception type thrown by futures.
* @ingroup exceptions
+ * @since C++11
*/
class future_error : public logic_error
{
@@ -178,11 +185,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
deferred
};
+ /// @cond undocumented
// _GLIBCXX_RESOLVE_LIB_DEFECTS
// 2021. Further incorrect usages of result_of
template<typename _Fn, typename... _Args>
using __async_result_of = typename __invoke_result<
typename decay<_Fn>::type, typename decay<_Args>::type...>::type;
+ /// @endcond
template<typename _Fn, typename... _Args>
future<__async_result_of<_Fn, _Args...>>
@@ -194,6 +203,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#if defined(_GLIBCXX_HAS_GTHREADS)
+ /// @cond undocumented
+
/// Base class and enclosing scope.
struct __future_base
{
@@ -655,8 +666,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
void _M_destroy() { delete this; }
};
+ /// @endcond
+
#ifndef _GLIBCXX_ASYNC_ABI_COMPAT
+ /// @cond undocumented
// Allow _Setter objects to be stored locally in std::function
template<typename _Res, typename _Arg>
struct __is_location_invariant
@@ -668,6 +682,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
struct __is_location_invariant
<__future_base::_Task_setter<_Res_ptr, _Fn, _Res>>
: true_type { };
+ /// @endcond
/// Common implementation for future and shared_future.
template<typename _Res>
@@ -1376,6 +1391,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
};
+ /// @cond undocumented
template<typename _Ptr_type, typename _Fn, typename _Res>
struct __future_base::_Task_setter
{
@@ -1512,6 +1528,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return __create_task_state<_Res(_Args...)>(std::move(_M_impl._M_fn),
static_cast<_Alloc&>(_M_impl));
}
+ /// @endcond
/// packaged_task
template<typename _Res, typename... _ArgTypes>
@@ -1648,6 +1665,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
: public true_type { };
#endif
+ /// @cond undocumented
+
// Shared state created by std::async().
// Holds a deferred function and storage for its result.
template<typename _BoundFn, typename _Res>
@@ -1761,7 +1780,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ptr_type _M_result;
_BoundFn _M_fn;
};
-
+ /// @endcond
/// async
template<typename _Fn, typename... _Args>
diff --git a/libstdc++-v3/include/std/thread b/libstdc++-v3/include/std/thread
index 92b24268ffe..82f191afe2d 100644
--- a/libstdc++-v3/include/std/thread
+++ b/libstdc++-v3/include/std/thread
@@ -50,6 +50,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @defgroup threads Threads
* @ingroup concurrency
+ * @since C++11
*
* Classes for thread support.
* @{
@@ -57,6 +58,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// std::thread is defined in <bits/std_thread.h>
+ /// @relates std::thread::id @{
+
#if __cpp_lib_three_way_comparison
inline strong_ordering
operator<=>(thread::id __x, thread::id __y) noexcept
@@ -96,9 +99,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
else
return __out << __id._M_thread;
}
+ /// @}
#ifdef __cpp_lib_jthread
+ /// @cond undocumented
#ifndef __STRICT_ANSI__
template<typename _Callable, typename... _Args>
constexpr bool __pmf_expects_stop_token = false;
@@ -108,8 +113,22 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
= __and_<is_member_function_pointer<remove_reference_t<_Callable>>,
is_invocable<_Callable, _Obj, stop_token, _Args...>>::value;
#endif
+ /// @endcond
- /// A thread that can be requested to stop and automatically joined.
+ /** A thread with cancellation and automatic joining.
+ *
+ * Unlike `std::thread`, destroying a joinable `std::jthread` will not
+ * terminate the process. Instead, it will try to request its thread to
+ * stop, then will join it.
+ *
+ * A `std::jthread` has a `std::stop_source` member which will be passed
+ * as the first argument to the callable that runs in the new thread
+ * (as long as the callable will accept that argument). That can then
+ * be used to send a stop request that the new thread can test for.
+ *
+ * @headerfile thread
+ * @since C++20
+ */
class jthread
{
public:
--
2.34.1
^ permalink raw reply [flat|nested] 12+ messages in thread
* [committed 11/12] libstdc++: Improve doxygen docs for some of <memory>
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (8 preceding siblings ...)
2022-05-13 12:40 ` [committed 10/12] libstdc++: Improve doxygen docs for <thread> and <future> Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 12/12] libstdc++: Improve doxygen docs for <mutex> Jonathan Wakely
10 siblings, 0 replies; 12+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* doc/doxygen/user.cfg.in (PREDEFINED): Define
_GLIBCXX23_CONSTEXPR macro.
* include/backward/auto_ptr.h (auto_ptr): Use @deprecated.
* include/bits/unique_ptr.h (default_delete): Use @since and
@headerfile.
* include/std/scoped_allocator: Remove @ingroup from @file
block.
---
libstdc++-v3/doc/doxygen/user.cfg.in | 1 +
libstdc++-v3/include/backward/auto_ptr.h | 4 ++++
libstdc++-v3/include/bits/unique_ptr.h | 13 ++++++++++---
libstdc++-v3/include/std/scoped_allocator | 1 -
4 files changed, 15 insertions(+), 4 deletions(-)
diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index cfda7ab13c4..4d21968cc57 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -2388,6 +2388,7 @@ PREDEFINED = __cplusplus=202002L \
_GLIBCXX14_CONSTEXPR=constexpr \
_GLIBCXX17_CONSTEXPR=constexpr \
_GLIBCXX20_CONSTEXPR=constexpr \
+ _GLIBCXX23_CONSTEXPR=constexpr \
"_GLIBCXX11_DEPRECATED= " \
"_GLIBCXX11_DEPRECATED_SUGGEST(E)= " \
"_GLIBCXX17_DEPRECATED= " \
diff --git a/libstdc++-v3/include/backward/auto_ptr.h b/libstdc++-v3/include/backward/auto_ptr.h
index 8725504d4c9..184ab403466 100644
--- a/libstdc++-v3/include/backward/auto_ptr.h
+++ b/libstdc++-v3/include/backward/auto_ptr.h
@@ -84,6 +84,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* _GLIBCXX_RESOLVE_LIB_DEFECTS
* 127. auto_ptr<> conversion issues
* These resolutions have all been incorporated.
+ *
+ * @headerfile memory
+ * @deprecated Deprecated in C++11, no longer in the standard since C++17.
+ * Use `unique_ptr` instead.
*/
template<typename _Tp>
class auto_ptr
diff --git a/libstdc++-v3/include/bits/unique_ptr.h b/libstdc++-v3/include/bits/unique_ptr.h
index ad60fada59b..e1ad7721a59 100644
--- a/libstdc++-v3/include/bits/unique_ptr.h
+++ b/libstdc++-v3/include/bits/unique_ptr.h
@@ -65,8 +65,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#pragma GCC diagnostic pop
#endif
- /// Primary template of default_delete, used by unique_ptr for single objects
- /// @since C++11
+ /** Primary template of default_delete, used by unique_ptr for single objects
+ *
+ * @headerfile memory
+ * @since C++11
+ */
template<typename _Tp>
struct default_delete
{
@@ -99,7 +102,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// _GLIBCXX_RESOLVE_LIB_DEFECTS
// DR 740 - omit specialization for array objects with a compile time length
- /// Specialization of default_delete for arrays, used by `unique_ptr<T[]>`
+ /** Specialization of default_delete for arrays, used by `unique_ptr<T[]>`
+ *
+ * @headerfile memory
+ * @since C++11
+ */
template<typename _Tp>
struct default_delete<_Tp[]>
{
diff --git a/libstdc++-v3/include/std/scoped_allocator b/libstdc++-v3/include/std/scoped_allocator
index f2e3ed9f783..c62b04874e2 100644
--- a/libstdc++-v3/include/std/scoped_allocator
+++ b/libstdc++-v3/include/std/scoped_allocator
@@ -24,7 +24,6 @@
/** @file include/scoped_allocator
* This is a Standard C++ Library header.
- * @ingroup allocators
*/
#ifndef _SCOPED_ALLOCATOR
--
2.34.1
^ permalink raw reply [flat|nested] 12+ messages in thread
* [committed 12/12] libstdc++: Improve doxygen docs for <mutex>
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (9 preceding siblings ...)
2022-05-13 12:40 ` [committed 11/12] libstdc++: Improve doxygen docs for some of <memory> Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
10 siblings, 0 replies; 12+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* doc/doxygen/user.cfg.in (PREDEFINED): Define
_GTHREAD_USE_MUTEX_TIMEDLOCK macro.
* include/bits/std_mutex.h (mutex, lock_guard): Use @since and
@headerfile.
* include/bits/unique_lock.h (unique_lock): Likewise.
* include/std/mutex (recursive_mutex, timed_mutex)
(recursive_timed_mutex, scoped_lock): Likewise.
---
libstdc++-v3/doc/doxygen/user.cfg.in | 1 +
libstdc++-v3/include/bits/std_mutex.h | 21 +++++++++++++-
libstdc++-v3/include/bits/unique_lock.h | 2 ++
libstdc++-v3/include/std/mutex | 38 +++++++++++++++++++++++--
4 files changed, 58 insertions(+), 4 deletions(-)
diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index 4d21968cc57..c034b864928 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -2325,6 +2325,7 @@ INCLUDE_FILE_PATTERNS =
PREDEFINED = __cplusplus=202002L \
__GTHREADS \
_GLIBCXX_HAS_GTHREADS \
+ _GTHREAD_USE_MUTEX_TIMEDLOCK \
_GLIBCXX_HAVE_TLS \
_GLIBCXX_INCLUDE_AS_CXX11 \
"_GLIBCXX_PURE= " \
diff --git a/libstdc++-v3/include/bits/std_mutex.h b/libstdc++-v3/include/bits/std_mutex.h
index d3a1d5eaec9..b22e0e12793 100644
--- a/libstdc++-v3/include/bits/std_mutex.h
+++ b/libstdc++-v3/include/bits/std_mutex.h
@@ -53,6 +53,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*/
#ifdef _GLIBCXX_HAS_GTHREADS
+ /// @cond undocumented
+
// Common base class for std::mutex and std::timed_mutex
class __mutex_base
{
@@ -78,8 +80,19 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
__mutex_base(const __mutex_base&) = delete;
__mutex_base& operator=(const __mutex_base&) = delete;
};
+ /// @endcond
- /// The standard mutex type.
+ /** The standard mutex type.
+ *
+ * A simple, non-recursive, non-timed mutex.
+ *
+ * Do not call `lock()` and `unlock()` directly, use a scoped lock type
+ * such as `std::unique_lock`, `std::lock_guard`, or (since C++17)
+ * `std::scoped_lock`.
+ *
+ * @headerfile mutex
+ * @since C++11
+ */
class mutex : private __mutex_base
{
public:
@@ -123,6 +136,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return &_M_mutex; }
};
+ /// @cond undocumented
+
// Implementation details for std::condition_variable
class __condvar
{
@@ -192,6 +207,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
__gthread_cond_t _M_cond;
#endif
};
+ /// @endcond
#endif // _GLIBCXX_HAS_GTHREADS
@@ -218,6 +234,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* A lock_guard controls mutex ownership within a scope, releasing
* ownership in the destructor.
+ *
+ * @headerfile mutex
+ * @since C++11
*/
template<typename _Mutex>
class lock_guard
diff --git a/libstdc++-v3/include/bits/unique_lock.h b/libstdc++-v3/include/bits/unique_lock.h
index 1f1aa15c463..9ed7ba25766 100644
--- a/libstdc++-v3/include/bits/unique_lock.h
+++ b/libstdc++-v3/include/bits/unique_lock.h
@@ -51,7 +51,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* to another unique_lock by move construction or move assignment. If a
* mutex lock is owned when the destructor runs ownership will be released.
*
+ * @headerfile mutex
* @ingroup mutexes
+ * @since C++11
*/
template<typename _Mutex>
class unique_lock
diff --git a/libstdc++-v3/include/std/mutex b/libstdc++-v3/include/std/mutex
index f500818d9c9..b9590bbf276 100644
--- a/libstdc++-v3/include/std/mutex
+++ b/libstdc++-v3/include/std/mutex
@@ -62,6 +62,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*/
#ifdef _GLIBCXX_HAS_GTHREADS
+ /// @cond undocumented
// Common base class for std::recursive_mutex and std::recursive_timed_mutex
class __recursive_mutex_base
@@ -89,8 +90,17 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ __gthread_recursive_mutex_destroy(&_M_mutex); }
#endif
};
+ /// @endcond
- /// The standard recursive mutex type.
+ /** The standard recursive mutex type.
+ *
+ * A recursive mutex can be locked more than once by the same thread.
+ * Other threads cannot lock the mutex until the owning thread unlocks it
+ * as many times as it was locked.
+ *
+ * @headerfile mutex
+ * @since C++11
+ */
class recursive_mutex : private __recursive_mutex_base
{
public:
@@ -132,6 +142,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
};
#if _GTHREAD_USE_MUTEX_TIMEDLOCK
+ /// @cond undocumented
+
template<typename _Derived>
class __timed_mutex_impl
{
@@ -207,8 +219,16 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return false;
}
};
+ /// @endcond
- /// The standard timed mutex type.
+ /** The standard timed mutex type.
+ *
+ * A non-recursive mutex that supports a timeout when trying to acquire the
+ * lock.
+ *
+ * @headerfile mutex
+ * @since C++11
+ */
class timed_mutex
: private __mutex_base, public __timed_mutex_impl<timed_mutex>
{
@@ -273,7 +293,16 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif
};
- /// recursive_timed_mutex
+ /** The standard recursive timed mutex type.
+ *
+ * A recursive mutex that supports a timeout when trying to acquire the
+ * lock. A recursive mutex can be locked more than once by the same thread.
+ * Other threads cannot lock the mutex until the owning thread unlocks it
+ * as many times as it was locked.
+ *
+ * @headerfile mutex
+ * @since C++11
+ */
class recursive_timed_mutex
: private __recursive_mutex_base,
public __timed_mutex_impl<recursive_timed_mutex>
@@ -687,6 +716,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* A scoped_lock controls mutex ownership within a scope, releasing
* ownership in the destructor.
+ *
+ * @headerfile mutex
+ * @since C++17
*/
template<typename... _MutexTypes>
class scoped_lock
--
2.34.1
^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2022-05-13 12:41 UTC | newest]
Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
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-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 ` [committed 07/12] libstdc++: Improve doxygen docs for <regex> Jonathan Wakely
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
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).