[gcc r12-2999] libstdc++: Improve doxygen documentation for std::unique_ptr

[gcc r12-2999] libstdc++: Improve doxygen documentation for std::unique_ptr

[Jonathan Wakely]

https://gcc.gnu.org/g:4fb471afc4f13ead1978fcdb008b92192412e9ba

commit r12-2999-g4fb471afc4f13ead1978fcdb008b92192412e9ba
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Wed Aug 18 15:03:19 2021 +0100

    libstdc++: Improve doxygen documentation for std::unique_ptr
    
    Add more detailed documentation for unique_ptr and related components.
    
    The new alias templates for the _MakeUniq SFINAE helper make the
    generated docs look better too.
    
    Signed-off-by: Jonathan Wakely <jwakely@redhat.com>
    
    libstdc++-v3/ChangeLog:
    
            * include/bits/unique_ptr.h (default_delete): Add @since tag.
            (unique_ptr, unique_ptr<T[]>): Likewise. Improve @brief.
            (make_unique, make_unique_for_overwrite): Likewise. Add @tparam,
            @param, and @returns.
            (_MakeUniq): Move to __detail namespace. Add alias template
            helpers.

Diff:
---
 libstdc++-v3/include/bits/unique_ptr.h | 84 ++++++++++++++++++++++++++--------
 1 file changed, 65 insertions(+), 19 deletions(-)

diff --git a/libstdc++-v3/include/bits/unique_ptr.h b/libstdc++-v3/include/bits/unique_ptr.h
index 2d8b9ed3fae..023bd4d7f31 100644
--- a/libstdc++-v3/include/bits/unique_ptr.h
+++ b/libstdc++-v3/include/bits/unique_ptr.h
@@ -58,6 +58,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif
 
   /// Primary template of default_delete, used by unique_ptr for single objects
+  /// @since C++11
   template<typename _Tp>
     struct default_delete
     {
@@ -236,7 +237,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     };
   /// @endcond
 
-  /// 20.7.1.2 unique_ptr for single objects.
+  // 20.7.1.2 unique_ptr for single objects.
+
+  /// A move-only smart pointer that manages unique ownership of a resource.
+  /// @since C++11
   template <typename _Tp, typename _Dp = default_delete<_Tp>>
     class unique_ptr
     {
@@ -468,10 +472,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       unique_ptr& operator=(const unique_ptr&) = delete;
   };
 
-  /// 20.7.1.3 unique_ptr for array objects with a runtime length
+  // 20.7.1.3 unique_ptr for array objects with a runtime length
   // [unique.ptr.runtime]
   // _GLIBCXX_RESOLVE_LIB_DEFECTS
   // DR 740 - omit specialization for array objects with a compile time length
+
+  /// A move-only smart pointer that manages unique ownership of an array.
+  /// @since C++11
   template<typename _Tp, typename _Dp>
     class unique_ptr<_Tp[], _Dp>
     {
@@ -939,7 +946,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #define __cpp_lib_make_unique 201304
 
   /// @cond undocumented
-
+namespace __detail
+{
   template<typename _Tp>
     struct _MakeUniq
     { typedef unique_ptr<_Tp> __single_object; };
@@ -952,54 +960,92 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     struct _MakeUniq<_Tp[_Bound]>
     { struct __invalid_type { }; };
 
+  template<typename _Tp>
+    using __unique_ptr_t = typename _MakeUniq<_Tp>::__single_object;
+  template<typename _Tp>
+    using __unique_ptr_array_t = typename _MakeUniq<_Tp>::__array;
+  template<typename _Tp>
+    using __invalid_make_unique_t = typename _MakeUniq<_Tp>::__invalid_type;
+}
   /// @endcond
 
-  /// @{
-  /// @relates unique_ptr
-
-  /// std::make_unique for single objects
+  /** Create an object owned by a `unique_ptr`.
+   *  @tparam _Tp A non-array object type.
+   *  @param __args Constructor arguments for the new object.
+   *  @returns A `unique_ptr<_Tp>` that owns the new object.
+   *  @since C++14
+   *  @relates unique_ptr
+   */
   template<typename _Tp, typename... _Args>
-    inline typename _MakeUniq<_Tp>::__single_object
+    inline __detail::__unique_ptr_t<_Tp>
     make_unique(_Args&&... __args)
     { return unique_ptr<_Tp>(new _Tp(std::forward<_Args>(__args)...)); }
 
-  /// std::make_unique for arrays of unknown bound
+  /** Create an array owned by a `unique_ptr`.
+   *  @tparam _Tp An array type of unknown bound, such as `U[]`.
+   *  @param __num The number of elements of type `U` in the new array.
+   *  @returns A `unique_ptr<U[]>` that owns the new array.
+   *  @since C++14
+   *  @relates unique_ptr
+   *
+   *  The array elements are value-initialized.
+   */
   template<typename _Tp>
-    inline typename _MakeUniq<_Tp>::__array
+    inline __detail::__unique_ptr_array_t<_Tp>
     make_unique(size_t __num)
     { return unique_ptr<_Tp>(new remove_extent_t<_Tp>[__num]()); }
 
-  /// Disable std::make_unique for arrays of known bound
+  /** Disable std::make_unique for arrays of known bound.
+   *  @tparam _Tp An array type of known bound, such as `U[N]`.
+   *  @since C++14
+   *  @relates unique_ptr
+   */
   template<typename _Tp, typename... _Args>
-    typename _MakeUniq<_Tp>::__invalid_type
+    __detail::__invalid_make_unique_t<_Tp>
     make_unique(_Args&&...) = delete;
 
 #if __cplusplus > 201703L
-  /// std::make_unique_for_overwrite for single objects
+  /** Create a default-initialied object owned by a `unique_ptr`.
+   *  @tparam _Tp A non-array object type.
+   *  @returns A `unique_ptr<_Tp>` that owns the new object.
+   *  @since C++20
+   *  @relates unique_ptr
+   */
   template<typename _Tp>
-    inline typename _MakeUniq<_Tp>::__single_object
+    inline __detail::__unique_ptr_t<_Tp>
     make_unique_for_overwrite()
     { return unique_ptr<_Tp>(new _Tp); }
 
-  /// std::make_unique_for_overwrite for arrays of unknown bound
+  /** Create a default-initialized array owned by a `unique_ptr`.
+   *  @tparam _Tp An array type of unknown bound, such as `U[]`.
+   *  @param __num The number of elements of type `U` in the new array.
+   *  @returns A `unique_ptr<U[]>` that owns the new array.
+   *  @since C++20
+   *  @relates unique_ptr
+   */
   template<typename _Tp>
-    inline typename _MakeUniq<_Tp>::__array
+    inline __detail::__unique_ptr_array_t<_Tp>
     make_unique_for_overwrite(size_t __n)
     { return unique_ptr<_Tp>(new remove_extent_t<_Tp>[__n]); }
 
-  /// Disable std::make_unique_for_overwrite for arrays of known bound
+  /** Disable std::make_unique_for_overwrite for arrays of known bound.
+   *  @tparam _Tp An array type of known bound, such as `U[N]`.
+   *  @since C++20
+   *  @relates unique_ptr
+   */
   template<typename _Tp, typename... _Args>
-    typename _MakeUniq<_Tp>::__invalid_type
+    __detail::__invalid_make_unique_t<_Tp>
     make_unique_for_overwrite(_Args&&...) = delete;
 #endif // C++20
 
-  /// @} relates unique_ptr
 #endif // C++14
 
 #if __cplusplus > 201703L && __cpp_concepts
   // _GLIBCXX_RESOLVE_LIB_DEFECTS
   // 2948. unique_ptr does not define operator<< for stream output
   /// Stream output operator for unique_ptr
+  /// @relates unique_ptr
+  /// @since C++20
   template<typename _CharT, typename _Traits, typename _Tp, typename _Dp>
     inline basic_ostream<_CharT, _Traits>&
     operator<<(basic_ostream<_CharT, _Traits>& __os,