public inbox for libstdc++-cvs@sourceware.org
help / color / mirror / Atom feed
* [gcc r12-2999] libstdc++: Improve doxygen documentation for std::unique_ptr
@ 2021-08-18 14:36 Jonathan Wakely
0 siblings, 0 replies; only message in thread
From: Jonathan Wakely @ 2021-08-18 14:36 UTC (permalink / raw)
To: gcc-cvs, libstdc++-cvs
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,
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2021-08-18 14:36 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-08-18 14:36 [gcc r12-2999] libstdc++: Improve doxygen documentation for std::unique_ptr Jonathan Wakely
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).