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.

3 files changed, 56 insertions, 26 deletions

diff --git a/libstdc++-v3/include/bits/atomic_base.h b/libstdc++-v3/include/bits/atomic_base.h
index 5cf217d..d29e443 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 ff86432..d4bd712 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 d819b6b..1c6acfa 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.