[gcc r14-291] libstdc++: Improve doxygen docs for <memory_resource>

[gcc r14-291] libstdc++: Improve doxygen docs for <memory_resource>

[Jonathan Wakely]

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

commit r14-291-gafcf2b09b8317d2777f44e830c3b8de1791312d5
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Wed Apr 26 22:50:03 2023 +0100

    libstdc++: Improve doxygen docs for <memory_resource>
    
    libstdc++-v3/ChangeLog:
    
            * include/bits/memory_resource.h: Improve doxygen comments.
            * include/std/memory_resource: Likewise.

Diff:
---
 libstdc++-v3/include/bits/memory_resource.h | 12 ++++++
 libstdc++-v3/include/std/memory_resource    | 63 +++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)

diff --git a/libstdc++-v3/include/bits/memory_resource.h b/libstdc++-v3/include/bits/memory_resource.h
index 1b9e51ddbbd..f12555d4215 100644
--- a/libstdc++-v3/include/bits/memory_resource.h
+++ b/libstdc++-v3/include/bits/memory_resource.h
@@ -53,6 +53,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 namespace pmr
 {
   /// Class memory_resource
+  /**
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   class memory_resource
   {
     static constexpr size_t _S_max_align = alignof(max_align_t);
@@ -104,6 +109,13 @@ namespace pmr
 #endif
 
   // C++17 23.12.3 Class template polymorphic_allocator
+
+  /// Class template polymorphic_allocator
+  /**
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   template<typename _Tp>
     class polymorphic_allocator
     {
diff --git a/libstdc++-v3/include/std/memory_resource b/libstdc++-v3/include/std/memory_resource
index 00859262470..fdfc23c95ed 100644
--- a/libstdc++-v3/include/std/memory_resource
+++ b/libstdc++-v3/include/std/memory_resource
@@ -24,6 +24,9 @@
 
 /** @file include/memory_resource
  *  This is a Standard C++ Library header.
+ *
+ *  This header declares the @ref pmr (std::pmr) memory resources.
+ *  @ingroup pmr
  */
 
 #ifndef _GLIBCXX_MEMORY_RESOURCE
@@ -35,6 +38,25 @@
 
 #if __cplusplus >= 201703L
 
+/**
+ * @defgroup pmr Polymorphic memory resources
+ *
+ * @anchor pmr
+ * @ingroup memory
+ * @since C++17
+ *
+ * Memory resources are classes that implement the `std::pmr::memory_resource`
+ * interface for allocating and deallocating memory. Unlike traditional C++
+ * allocators, memory resources are not value types and are used via pointers
+ * to the abstract base class. They are only responsible for allocating and
+ * deallocating, not for construction and destruction of objects. As a result,
+ * memory resources just allocate raw memory as type `void*` and are not
+ * templates that allocate/deallocate and construct/destroy a specific type.
+ *
+ * The class template `std::pmr::polymorphic_allocator` is an allocator that
+ * uses a memory resource for its allocations.
+ */
+
 #include <bits/memory_resource.h>
 #include <vector>			// vector
 #include <shared_mutex>			// shared_mutex
@@ -63,6 +85,11 @@ namespace pmr
   // Global memory resources
 
   /// A pmr::memory_resource that uses `new` to allocate memory
+  /**
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   [[nodiscard, __gnu__::__returns_nonnull__, __gnu__::__const__]]
   memory_resource*
   new_delete_resource() noexcept;
@@ -91,6 +118,11 @@ namespace pmr
   class monotonic_buffer_resource;
 
   /// Parameters for tuning a pool resource's behaviour.
+  /**
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   struct pool_options
   {
     /** @brief Upper limit on number of blocks in a chunk.
@@ -152,6 +184,11 @@ namespace pmr
 
 #ifdef _GLIBCXX_HAS_GTHREADS
   /// A thread-safe memory resource that manages pools of fixed-size blocks.
+  /**
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   class synchronized_pool_resource : public memory_resource
   {
   public:
@@ -218,6 +255,11 @@ namespace pmr
 #endif
 
   /// A non-thread-safe memory resource that manages pools of fixed-size blocks.
+  /**
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   class unsynchronized_pool_resource : public memory_resource
   {
   public:
@@ -275,6 +317,27 @@ namespace pmr
     _Pool* _M_pools = nullptr;
   };
 
+  /// A memory resource that allocates from a fixed-size buffer.
+  /**
+   * The main feature of a `pmr::monotonic_buffer_resource` is that its
+   * `do_deallocate` does nothing. This makes it very fast because there is no
+   * need to manage a free list, and every allocation simply returns a new
+   * block of memory, rather than searching for a suitably-sized free block.
+   * Because deallocating is a no-op, the amount of memory used by the resource
+   * only grows until `release()` (or the destructor) is called to return all
+   * memory to upstream.
+   *
+   * A `monotonic_buffer_resource` can be initialized with a buffer that
+   * will be used to satisfy all allocation requests, until the buffer is full.
+   * After that a new buffer will be allocated from the upstream resource.
+   * By using a stack buffer and `pmr::null_memory_resource()` as the upstream
+   * you can get a memory resource that only uses the stack and never
+   * dynamically allocates.
+   *
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   class monotonic_buffer_resource : public memory_resource
   {
   public: