[committed 08/12] libstdc++: Improve doxygen docs for std::allocator

[Jonathan Wakely <jwakely@redhat.com>]

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