diff options
author | Jonathan Wakely <jwakely@redhat.com> | 2022-05-12 13:44:52 +0100 |
---|---|---|
committer | Jonathan Wakely <jwakely@redhat.com> | 2024-03-18 13:50:56 +0000 |
commit | 54de91d55980e063a8630193cd3a2ef457508735 (patch) | |
tree | 02f4f69de09fa0c0e3a89f039ef88c1e29c857ac /libstdc++-v3/include | |
parent | e1800b8dad5d7e207cc9617f530e5d4fb06a738c (diff) | |
download | gcc-54de91d55980e063a8630193cd3a2ef457508735.zip gcc-54de91d55980e063a8630193cd3a2ef457508735.tar.gz gcc-54de91d55980e063a8630193cd3a2ef457508735.tar.bz2 |
libstdc++: Improve doxygen docs for std::allocator
libstdc++-v3/ChangeLog:
* doc/doxygen/user.cfg.in (PREDEFINED): Define __allocator_base
so that Doxygen shows the right base-class for std::allocator.
* include/bits/alloc_traits.h: Improve doxygen docs.
* include/bits/allocator.h: Likewise.
* include/bits/new_allocator.h: Likewise.
* include/ext/new_allocator.h: Likewise.
(cherry picked from commit 171f41f124bc1d5d80a395d27833a578cceba9e7)
Diffstat (limited to 'libstdc++-v3/include')
-rw-r--r-- | libstdc++-v3/include/bits/alloc_traits.h | 5 | ||||
-rw-r--r-- | libstdc++-v3/include/bits/allocator.h | 15 | ||||
-rw-r--r-- | libstdc++-v3/include/bits/new_allocator.h | 19 | ||||
-rw-r--r-- | libstdc++-v3/include/ext/new_allocator.h | 12 |
4 files changed, 41 insertions, 10 deletions
diff --git a/libstdc++-v3/include/bits/alloc_traits.h b/libstdc++-v3/include/bits/alloc_traits.h index 25496bc..4f40b36 100644 --- a/libstdc++-v3/include/bits/alloc_traits.h +++ b/libstdc++-v3/include/bits/alloc_traits.h @@ -661,6 +661,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { return __rhs; } }; + /// @cond undocumented #if __cplusplus < 201703L template<typename _Alloc> inline void @@ -818,8 +819,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION __a.deallocate(__a.allocate(1u), 1u); }; #endif + /// @endcond #endif // C++11 + /// @cond undocumented + /** * Destroy a range of objects using the supplied allocator. For * non-default allocators we do not optimize away invocation of @@ -849,6 +853,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { std::_Destroy(__first, __last); } + /// @endcond _GLIBCXX_END_NAMESPACE_VERSION } // namespace std diff --git a/libstdc++-v3/include/bits/allocator.h b/libstdc++-v3/include/bits/allocator.h index a4b80d9..aec0b37 100644 --- a/libstdc++-v3/include/bits/allocator.h +++ b/libstdc++-v3/include/bits/allocator.h @@ -67,7 +67,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION // explicit specialization, with the historical ABI properties, but with // the same members that are present in the primary template. - /// allocator<void> specialization. + /** std::allocator<void> specialization. + * + * @headerfile memory + */ template<> class allocator<void> { @@ -119,6 +122,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * for further details. * * @tparam _Tp Type of allocated object. + * + * @headerfile memory */ template<typename _Tp> class allocator : public __allocator_base<_Tp> @@ -214,6 +219,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION // Inherit everything else. }; + /** Equality comparison for std::allocator objects + * + * @return true, for all std::allocator objects. + * @relates std::allocator + */ template<typename _T1, typename _T2> inline _GLIBCXX20_CONSTEXPR bool operator==(const allocator<_T1>&, const allocator<_T2>&) @@ -228,6 +238,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { return false; } #endif + /// @cond undocumented + // Invalid allocator<cv T> partial specializations. // allocator_traits::rebind_alloc can be used to form a valid allocator type. template<typename _Tp> @@ -330,6 +342,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } }; #endif + /// @endcond _GLIBCXX_END_NAMESPACE_VERSION } // namespace std diff --git a/libstdc++-v3/include/bits/new_allocator.h b/libstdc++-v3/include/bits/new_allocator.h index d066d01..e9eb103 100644 --- a/libstdc++-v3/include/bits/new_allocator.h +++ b/libstdc++-v3/include/bits/new_allocator.h @@ -43,14 +43,21 @@ namespace std _GLIBCXX_VISIBILITY(default) _GLIBCXX_BEGIN_NAMESPACE_VERSION /** - * @brief An allocator that uses global new, as per C++03 [20.4.1]. - * @ingroup allocators + * @brief An allocator that uses global `new`, as per C++03 [20.4.1]. + * @ingroup allocators * - * This is precisely the allocator defined in the C++ Standard. - * - all allocation calls operator new - * - all deallocation calls operator delete + * This is precisely the allocator defined in the C++ Standard. + * - all allocation calls `operator new` + * - all deallocation calls `operator delete` * - * @tparam _Tp Type of allocated object. + * This is the default base-class implementation of `std::allocator`, + * and is also the base-class of the `__gnu_cxx::new_allocator` extension. + * You should use either `std::allocator` or `__gnu_cxx::new_allocator` + * instead of using this directly. + * + * @tparam _Tp Type of allocated object. + * + * @headerfile memory */ template<typename _Tp> class __new_allocator diff --git a/libstdc++-v3/include/ext/new_allocator.h b/libstdc++-v3/include/ext/new_allocator.h index b8f5fcc..96e6523 100644 --- a/libstdc++-v3/include/ext/new_allocator.h +++ b/libstdc++-v3/include/ext/new_allocator.h @@ -36,14 +36,20 @@ namespace __gnu_cxx _GLIBCXX_VISIBILITY(default) _GLIBCXX_BEGIN_NAMESPACE_VERSION /** - * @brief An allocator that uses global new, as per C++03 [20.4.1]. + * @brief An allocator that uses global `new`, as per C++03 [20.4.1]. * @ingroup allocators * * This is precisely the allocator defined in the C++ Standard. - * - all allocation calls operator new - * - all deallocation calls operator delete + * - all allocation calls `operator new` + * - all deallocation calls `operator delete` + * + * This is a non-standard extension that can be used to guarantee + * allocation from `new` even if the library has been configured to + * use a different implementation for `std::allocator`. * * @tparam _Tp Type of allocated object. + * + * @headerfile ext/new_allocator.h */ template<typename _Tp> class new_allocator : public std::__new_allocator<_Tp> |