From c05ab418b30ebf00f02e43c697254ebcaa8cc579 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Thu, 2 May 2019 16:45:04 +0100 Subject: [PATCH] Improve API docs for and * config/allocator/new_allocator_base.h (__allocator_base): Add workaround for Doxygen bug #6945. * include/std/memory: Improve docs. Define group for pointer safety. * include/std/scoped_allocator: Improve docs. Use "undocumented" conditional to suppress documentation for implementation details. From-SVN: r270807 --- libstdc++-v3/ChangeLog | 6 +++ .../config/allocator/new_allocator_base.h | 2 +- libstdc++-v3/include/std/memory | 39 +++++++++++++++++-- libstdc++-v3/include/std/scoped_allocator | 10 ++++- 4 files changed, 51 insertions(+), 6 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 596d485ff0f..8b15504840c 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,5 +1,11 @@ 2019-05-02 Jonathan Wakely + * config/allocator/new_allocator_base.h (__allocator_base): Add + workaround for Doxygen bug #6945. + * include/std/memory: Improve docs. Define group for pointer safety. + * include/std/scoped_allocator: Improve docs. Use "undocumented" + conditional to suppress documentation for implementation details. + * include/bits/specfun.h: Improve docs. * include/tr1/cmath: Likewise. Fix nesting of preprocessor conditions and namespaces. diff --git a/libstdc++-v3/config/allocator/new_allocator_base.h b/libstdc++-v3/config/allocator/new_allocator_base.h index 77ea9df56a2..a81ca96f86b 100644 --- a/libstdc++-v3/config/allocator/new_allocator_base.h +++ b/libstdc++-v3/config/allocator/new_allocator_base.h @@ -37,11 +37,11 @@ namespace std { /** * @brief An alias to the base class for std::allocator. - * @ingroup allocators * * Used to set the std::allocator base class to * __gnu_cxx::new_allocator. * + * @ingroup allocators * @tparam _Tp Type of allocated object. */ template diff --git a/libstdc++-v3/include/std/memory b/libstdc++-v3/include/std/memory index 6677fe782de..f00e0abd0eb 100644 --- a/libstdc++-v3/include/std/memory +++ b/libstdc++-v3/include/std/memory @@ -38,6 +38,7 @@ /** @file include/memory * This is a Standard C++ Library header. + * @ingroup memory */ #ifndef _GLIBCXX_MEMORY @@ -100,19 +101,21 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** * @brief Fit aligned storage in buffer. - * - * [ptr.align] + * @ingroup memory * * This function tries to fit @a __size bytes of storage with alignment * @a __align into the buffer @a __ptr of size @a __space bytes. If such * a buffer fits then @a __ptr is changed to point to the first byte of the * aligned storage and @a __space is reduced by the bytes used for alignment. * + * C++11 20.6.5 [ptr.align] + * * @param __align A fundamental or extended alignment value. * @param __size Size of the aligned storage required. * @param __ptr Pointer to a buffer of @a __space bytes. * @param __space Size of the buffer pointed to by @a __ptr. * @return the updated pointer if the aligned storage fits, otherwise nullptr. + * */ inline void* align(size_t __align, size_t __size, void*& __ptr, size_t& __space) noexcept @@ -136,28 +139,52 @@ align(size_t __align, size_t __size, void*& __ptr, size_t& __space) noexcept } } -// 20.7.4 [util.dynamic.safety], pointer safety +/** @defgroup ptr_safety Pointer Safety and Garbage Collection + * @ingroup memory + * + * Utilities to assist with garbage collection in an implementation + * that supports strict pointer safety. + * This implementation only supports relaxed pointer safety + * and so these functions have no effect. + * + * C++11 20.6.4 [util.dynamic.safety], Pointer safety + * + * @{ + */ +/// Constants representing the different types of pointer safety. enum class pointer_safety { relaxed, preferred, strict }; +/// Inform a garbage collector that an object is still in use. inline void declare_reachable(void*) { } +/// Unregister an object previously registered with declare_reachable. template inline _Tp* undeclare_reachable(_Tp* __p) { return __p; } +/// Inform a garbage collector that a region of memory need not be traced. inline void declare_no_pointers(char*, size_t) { } +/// Unregister a range previously registered with declare_no_pointers. inline void undeclare_no_pointers(char*, size_t) { } +/// The type of pointer safety supported by the implementation. inline pointer_safety get_pointer_safety() noexcept { return pointer_safety::relaxed; } +// @} #if __cplusplus > 201703L - /// Inform the compiler that a pointer is aligned. + /** @brief Inform the compiler that a pointer is aligned. + * + * @tparam _Align An alignment value (i.e. a power of two) + * @tparam _Tp An object type + * @param __ptr A pointer that is aligned to _Align + * @ingroup memory + */ template [[nodiscard,__gnu__::__always_inline__]] constexpr _Tp* assume_aligned(_Tp* __ptr) @@ -176,6 +203,9 @@ get_pointer_safety() noexcept { return pointer_safety::relaxed; } template struct __is_pair> : true_type { }; +/** @addtogroup allocators + * @{ + */ template>>, typename _Alloc, typename... _Args> constexpr auto @@ -358,6 +388,7 @@ get_pointer_safety() noexcept { return pointer_safety::relaxed; } return ::new(__vp) _Tp(std::make_obj_using_allocator<_Tp>(__a, std::forward<_Args>(__args)...)); } +// @} #endif // C++2a diff --git a/libstdc++-v3/include/std/scoped_allocator b/libstdc++-v3/include/std/scoped_allocator index 2c7ad8e94d7..04a23ed423a 100644 --- a/libstdc++-v3/include/std/scoped_allocator +++ b/libstdc++-v3/include/std/scoped_allocator @@ -24,6 +24,7 @@ /** @file include/scoped_allocator * This is a Standard C++ Library header. + * @ingroup allocators */ #ifndef _SCOPED_ALLOCATOR @@ -49,6 +50,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * @{ */ + /// @cond undocumented + template using __outer_allocator_t = decltype(std::declval<_Alloc>().outer_allocator()); @@ -75,6 +78,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { return __base::_S_outermost(__a.outer_allocator()); } }; + /// Implementation of the OUTERMOST pseudofunction template inline typename __outermost_type<_Alloc>::type& __outermost(_Alloc& __a) @@ -164,7 +168,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION __type _M_inner; }; - /// Primary class template. + /// @endcond + + /// An adaptor to recursively pass an allocator to the objects it constructs template class scoped_allocator_adaptor : public _OuterAlloc @@ -484,6 +490,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #endif // C++17 }; + /// @related std::scoped_allocator_adaptor template inline bool operator==(const scoped_allocator_adaptor<_OutA1, _InA...>& __a, @@ -493,6 +500,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION && __a._M_inner == __b._M_inner; } + /// @related std::scoped_allocator_adaptor template inline bool operator!=(const scoped_allocator_adaptor<_OutA1, _InA...>& __a, -- 2.30.2