From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2181) id D704C39874CB; Wed, 18 Aug 2021 14:36:34 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org D704C39874CB MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="utf-8" From: Jonathan Wakely To: gcc-cvs@gcc.gnu.org, libstdc++-cvs@gcc.gnu.org Subject: [gcc r12-2999] libstdc++: Improve doxygen documentation for std::unique_ptr X-Act-Checkin: gcc X-Git-Author: Jonathan Wakely X-Git-Refname: refs/heads/master X-Git-Oldrev: 828176ba490d034d5d689f7733466530c25c5ed3 X-Git-Newrev: 4fb471afc4f13ead1978fcdb008b92192412e9ba Message-Id: <20210818143634.D704C39874CB@sourceware.org> Date: Wed, 18 Aug 2021 14:36:34 +0000 (GMT) X-BeenThere: libstdc++-cvs@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libstdc++-cvs mailing list List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 18 Aug 2021 14:36:34 -0000 https://gcc.gnu.org/g:4fb471afc4f13ead1978fcdb008b92192412e9ba commit r12-2999-g4fb471afc4f13ead1978fcdb008b92192412e9ba Author: Jonathan Wakely 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 libstdc++-v3/ChangeLog: * include/bits/unique_ptr.h (default_delete): Add @since tag. (unique_ptr, unique_ptr): 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 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 > 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 class unique_ptr<_Tp[], _Dp> { @@ -939,7 +946,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #define __cpp_lib_make_unique 201304 /// @cond undocumented - +namespace __detail +{ template struct _MakeUniq { typedef unique_ptr<_Tp> __single_object; }; @@ -952,54 +960,92 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION struct _MakeUniq<_Tp[_Bound]> { struct __invalid_type { }; }; + template + using __unique_ptr_t = typename _MakeUniq<_Tp>::__single_object; + template + using __unique_ptr_array_t = typename _MakeUniq<_Tp>::__array; + template + 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 - 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` that owns the new array. + * @since C++14 + * @relates unique_ptr + * + * The array elements are value-initialized. + */ template - 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 _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 - 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` that owns the new array. + * @since C++20 + * @relates unique_ptr + */ template - 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 _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 inline basic_ostream<_CharT, _Traits>& operator<<(basic_ostream<_CharT, _Traits>& __os,