[gcc r12-10267] libstdc++: Improve doxygen docs for <atomic>

[gcc r12-10267] libstdc++: Improve doxygen docs for <atomic>

[Jonathan Wakely]

https://gcc.gnu.org/g:f0db5dfce8c729def8ce12ff7e3ed3b1e4f49467

commit r12-10267-gf0db5dfce8c729def8ce12ff7e3ed3b1e4f49467
Author: Jonathan Wakely <jwakely@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.