Improve API docs for <memory> and <scoped_allocator>

	* config/allocator/new_allocator_base.h (__allocator_base): Add
	workaround for Doxygen bug #6945.
	* include/std/memory: Improve docs. Define group for pointer safety.
	* include/std/scoped_allocator: Improve docs. Use "undocumented"
	conditional to suppress documentation for implementation details.

From-SVN: r270807

4 files changed, 51 insertions, 6 deletions

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index 596d485..8b15504 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,5 +1,11 @@
 2019-05-02  Jonathan Wakely  <jwakely@redhat.com>
 
+	* config/allocator/new_allocator_base.h (__allocator_base): Add
+	workaround for Doxygen bug #6945.
+	* include/std/memory: Improve docs. Define group for pointer safety.
+	* include/std/scoped_allocator: Improve docs. Use "undocumented"
+	conditional to suppress documentation for implementation details.
+
 	* include/bits/specfun.h: Improve docs.
 	* include/tr1/cmath: Likewise. Fix nesting of preprocessor conditions
 	and namespaces.
diff --git a/libstdc++-v3/config/allocator/new_allocator_base.h b/libstdc++-v3/config/allocator/new_allocator_base.h
index 77ea9df..a81ca96 100644
--- a/libstdc++-v3/config/allocator/new_allocator_base.h
+++ b/libstdc++-v3/config/allocator/new_allocator_base.h
@@ -37,11 +37,11 @@ namespace std
 {
   /**
    *  @brief  An alias to the base class for std::allocator.
-   *  @ingroup allocators
    *
    *  Used to set the std::allocator base class to
    *  __gnu_cxx::new_allocator.
    *
+   *  @ingroup allocators
    *  @tparam  _Tp  Type of allocated object.
     */
   template<typename _Tp>
diff --git a/libstdc++-v3/include/std/memory b/libstdc++-v3/include/std/memory
index 6677fe7..f00e0ab 100644
--- a/libstdc++-v3/include/std/memory
+++ b/libstdc++-v3/include/std/memory
@@ -38,6 +38,7 @@
 
 /** @file include/memory
  *  This is a Standard C++ Library header.
+ *  @ingroup memory
  */
 
 #ifndef _GLIBCXX_MEMORY
@@ -100,19 +101,21 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
 /**
  *  @brief Fit aligned storage in buffer.
- *
- *  [ptr.align]
+ *  @ingroup memory
  *
  *  This function tries to fit @a __size bytes of storage with alignment
  *  @a __align into the buffer @a __ptr of size @a __space bytes.  If such
  *  a buffer fits then @a __ptr is changed to point to the first byte of the
  *  aligned storage and @a __space is reduced by the bytes used for alignment.
  *
+ *  C++11 20.6.5 [ptr.align]
+ *
  *  @param __align   A fundamental or extended alignment value.
  *  @param __size    Size of the aligned storage required.
  *  @param __ptr     Pointer to a buffer of @a __space bytes.
  *  @param __space   Size of the buffer pointed to by @a __ptr.
  *  @return the updated pointer if the aligned storage fits, otherwise nullptr.
+ *
  */
 inline void*
 align(size_t __align, size_t __size, void*& __ptr, size_t& __space) noexcept
@@ -136,28 +139,52 @@ align(size_t __align, size_t __size, void*& __ptr, size_t& __space) noexcept
     }
 }
 
-// 20.7.4 [util.dynamic.safety], pointer safety
+/** @defgroup ptr_safety Pointer Safety and Garbage Collection
+ *  @ingroup memory
+ *
+ * Utilities to assist with garbage collection in an implementation
+ * that supports <em>strict pointer safety</em>.
+ * This implementation only supports <em>relaxed pointer safety</em>
+ * and so these functions have no effect.
+ *
+ * C++11 20.6.4 [util.dynamic.safety], Pointer safety
+ *
+ * @{
+ */
 
+/// Constants representing the different types of pointer safety.
 enum class pointer_safety { relaxed, preferred, strict };
 
+/// Inform a garbage collector that an object is still in use.
 inline void
 declare_reachable(void*) { }
 
+/// Unregister an object previously registered with declare_reachable.
 template <typename _Tp>
   inline _Tp*
   undeclare_reachable(_Tp* __p) { return __p; }
 
+/// Inform a garbage collector that a region of memory need not be traced.
 inline void
 declare_no_pointers(char*, size_t) { }
 
+/// Unregister a range previously registered with declare_no_pointers.
 inline void
 undeclare_no_pointers(char*, size_t) { }
 
+/// The type of pointer safety supported by the implementation.
 inline pointer_safety
 get_pointer_safety() noexcept { return pointer_safety::relaxed; }
+// @}
 
 #if __cplusplus > 201703L
-  /// Inform the compiler that a pointer is aligned.
+  /** @brief Inform the compiler that a pointer is aligned.
+   *
+   *  @tparam _Align An alignment value (i.e. a power of two)
+   *  @tparam _Tp    An object type
+   *  @param  __ptr  A pointer that is aligned to _Align
+   *  @ingroup memory
+   */
   template<size_t _Align, class _Tp>
     [[nodiscard,__gnu__::__always_inline__]]
     constexpr _Tp* assume_aligned(_Tp* __ptr)
@@ -176,6 +203,9 @@ get_pointer_safety() noexcept { return pointer_safety::relaxed; }
   template<typename _Tp, typename _Up>
     struct __is_pair<const pair<_Tp, _Up>> : true_type { };
 
+/** @addtogroup allocators
+ *  @{
+ */
   template<typename _Tp, typename __ = _Require<__not_<__is_pair<_Tp>>>,
 	   typename _Alloc, typename... _Args>
     constexpr auto
@@ -358,6 +388,7 @@ get_pointer_safety() noexcept { return pointer_safety::relaxed; }
       return ::new(__vp) _Tp(std::make_obj_using_allocator<_Tp>(__a,
 	    std::forward<_Args>(__args)...));
     }
+// @}
 
 #endif // C++2a
 
diff --git a/libstdc++-v3/include/std/scoped_allocator b/libstdc++-v3/include/std/scoped_allocator
index 2c7ad8e..04a23ed 100644
--- a/libstdc++-v3/include/std/scoped_allocator
+++ b/libstdc++-v3/include/std/scoped_allocator
@@ -24,6 +24,7 @@
 
 /** @file include/scoped_allocator
  *  This is a Standard C++ Library header.
+ *  @ingroup allocators
  */
 
 #ifndef _SCOPED_ALLOCATOR
@@ -49,6 +50,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    * @{
    */
 
+  /// @cond undocumented
+
   template<typename _Alloc>
     using __outer_allocator_t
       = decltype(std::declval<_Alloc>().outer_allocator());
@@ -75,6 +78,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       { return __base::_S_outermost(__a.outer_allocator()); }
     };
 
+  /// Implementation of the OUTERMOST pseudofunction
   template<typename _Alloc>
     inline typename __outermost_type<_Alloc>::type&
     __outermost(_Alloc& __a)
@@ -164,7 +168,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       __type _M_inner;
     };
 
-  /// Primary class template.
+  /// @endcond
+
+  /// An adaptor to recursively pass an allocator to the objects it constructs
   template<typename _OuterAlloc, typename... _InnerAllocs>
     class scoped_allocator_adaptor
     : public _OuterAlloc
@@ -484,6 +490,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif // C++17
     };
 
+  /// @related std::scoped_allocator_adaptor
   template <typename _OutA1, typename _OutA2, typename... _InA>
     inline bool
     operator==(const scoped_allocator_adaptor<_OutA1, _InA...>& __a,
@@ -493,6 +500,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
           && __a._M_inner == __b._M_inner;
     }
 
+  /// @related std::scoped_allocator_adaptor
   template <typename _OutA1, typename _OutA2, typename... _InA>
     inline bool
     operator!=(const scoped_allocator_adaptor<_OutA1, _InA...>& __a,