From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTP id 274CC398B842 for ; Wed, 18 Aug 2021 14:42:32 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 274CC398B842 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-394-tAGVQRrRMC2WuZNkfKsP1A-1; Wed, 18 Aug 2021 10:42:30 -0400 X-MC-Unique: tAGVQRrRMC2WuZNkfKsP1A-1 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 48AFD100CA89; Wed, 18 Aug 2021 14:42:29 +0000 (UTC) Received: from localhost (unknown [10.33.36.8]) by smtp.corp.redhat.com (Postfix) with ESMTP id E5F2310016FF; Wed, 18 Aug 2021 14:42:28 +0000 (UTC) Date: Wed, 18 Aug 2021 15:42:28 +0100 From: Jonathan Wakely To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed] libstdc++: Improve doxygen documentation for std::unique_ptr Message-ID: MIME-Version: 1.0 X-Clacks-Overhead: GNU Terry Pratchett X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: multipart/mixed; boundary="mFPmP82vpEIuYoze" Content-Disposition: inline X-Spam-Status: No, score=-14.2 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: libstdc++@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libstdc++ mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 18 Aug 2021 14:42:33 -0000 --mFPmP82vpEIuYoze Content-Type: text/plain; charset=us-ascii Content-Disposition: inline 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. Tested powerpc64le-linux. Committed to trunk. --mFPmP82vpEIuYoze Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="patch.txt" commit 4fb471afc4f13ead1978fcdb008b92192412e9ba Author: Jonathan Wakely Date: Wed Aug 18 15:03:19 2021 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 --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, --mFPmP82vpEIuYoze--