https://gcc.gnu.org/g:f0db5dfce8c729def8ce12ff7e3ed3b1e4f49467
commit r12-10267-gf0db5dfce8c729def8ce12ff7e3ed3b1e4f49467
Author: Jonathan Wakely <jwak...@redhat.com>
Date: Wed May 11 23:52:20 2022 +0100
libstdc++: Improve doxygen docs for <atomic>
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.
(cherry picked from commit 1566ca0969ac4a14f7434d710e75dd89da303e75)
Diff:
---
libstdc++-v3/include/bits/atomic_base.h | 39 ++++++++++++++++++++-------
libstdc++-v3/include/bits/shared_ptr_atomic.h | 32 +++++++++++++---------
libstdc++-v3/include/std/atomic | 8 +++---
3 files changed, 54 insertions(+), 25 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,16 +155,17 @@ _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
+#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 }
@@ -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 e903fe89424..51ad32ce21b 100644
--- a/libstdc++-v3/include/bits/shared_ptr_atomic.h
+++ b/libstdc++-v3/include/bits/shared_ptr_atomic.h
@@ -64,9 +64,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @addtogroup pointer_abstractions
+ * @relates shared_ptr
* @{
*/
- /// @relates shared_ptr @{
/// @cond undocumented
@@ -120,8 +120,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>
@@ -156,8 +156,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>
@@ -193,8 +193,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>
@@ -240,10 +240,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>
@@ -353,11 +353,19 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
/// @}
+ /// @} group pointer_abstractions
+
#if __cplusplus >= 202002L
# define __cpp_lib_atomic_shared_ptr 201711L
template<typename _Tp>
struct atomic;
+ /**
+ * @addtogroup pointer_abstractions
+ * @relates shared_ptr
+ * @{
+ */
+
template<typename _Up>
static constexpr bool __is_shared_ptr = false;
template<typename _Up>
@@ -836,10 +844,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 94150c1181f..52a7b0ad10b 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.
