[committed] libstdc++: Improve doxygen docs for
Tested powerpc64le-linux. Pushed to trunk.
-- >8 --
Add @headerfile and @since tags. Add gamma_distribution to the correct
group (poisson distributions). Add a group for the sampling
distributions and add the missing definitions of their probability
functions. Add uniform_int_distribution back to the uniform
distributions group.
libstdc++-v3/ChangeLog:
* include/bits/random.h (gamma_distribution): Add to the right
doxygen group.
(discrete_distribution, piecewise_constant_distribution)
(piecewise_linear_distribution): Create a new doxygen group and
fix the incomplete doxygen comments.
* include/bits/uniform_int_dist.h (uniform_int_distribution):
Add to doxygen group.
---
libstdc++-v3/include/bits/random.h | 127 ++-
libstdc++-v3/include/bits/uniform_int_dist.h | 11 ++
2 files changed, 132 insertions(+), 6 deletions(-)
diff --git a/libstdc++-v3/include/bits/random.h
b/libstdc++-v3/include/bits/random.h
index 42f37c1e77e..f77005adec5 100644
--- a/libstdc++-v3/include/bits/random.h
+++ b/libstdc++-v3/include/bits/random.h
@@ -256,6 +256,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* parameters @p __a and @p __c must be less than @p __m.
*
* The size of the state is @f$1@f$.
+ *
+ * @headerfile random
+ * @since C++11
*/
template
class linear_congruential_engine
@@ -471,6 +474,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @tparam __c The second left-shift tempering matrix mask.
* @tparam __l The second right-shift tempering matrix parameter.
* @tparam __f Initialization multiplier.
+ *
+ * @headerfile random
+ * @since C++11
*/
template
class subtract_with_carry_engine
@@ -890,7 +899,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* Produces random numbers from some base engine by discarding blocks of
* data.
*
- * 0 <= @p __r <= @p __p
+ * @pre @f$ 0 \leq r \leq p @f$
+ *
+ * @headerfile random
+ * @since C++11
*/
template
class discard_block_engine
@@ -1114,6 +1126,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* Produces random numbers by combining random numbers from some base
* engine to produce random numbers with a specified number of bits @p __w.
+ *
+ * @headerfile random
+ * @since C++11
*/
template
class independent_bits_engine
@@ -1338,6 +1353,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* The values from the base engine are stored in a sequence of size @p __k
* and shuffled by an algorithm that depends on those values.
+ *
+ * @headerfile random
+ * @since C++11
*/
template
class shuffle_order_engine
@@ -1625,6 +1643,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* A standard interface to a platform-specific non-deterministic
* random number generator (if any are available).
+ *
+ * @headerfile random
+ * @since C++11
*/
class random_device
{
@@ -1750,6 +1771,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* A continuous random distribution on the range [min, max) with equal
* probability throughout the range. The URNG should be real-valued and
* deliver number in the range [0, 1).
+ *
+ * @headerfile random
+ * @since C++11
*/
template
class uniform_real_distribution
@@ -1984,6 +2008,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* p(x|\mu,\sigma) = \frac{1}{\sigma \sqrt{2 \pi}}
*e^{- \frac{{x - \mu}^ {2}}{2 \sigma ^ {2}} }
* @f]
+ *
+ * @headerfile random
+ * @since C++11
*/
template
class normal_distribution
@@ -2208,6 +2235,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* p(x|m,s) = \frac{1}{sx\sqrt{2\pi}}
*\exp{-\frac{(\ln{x} - m)^2}{2s^2}}
* @f]
+ *
+ * @headerfile random
+ * @since C++11
*/
template
class lognormal_distribution
@@ -2414,6 +2444,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return !(__d1 == __d2); }
#endif
+ /// @} group random_distributions_normal
+
+ /**
+ * @addtogroup random_distributions_poisson Poisson Distributions
+ * @ingroup random_distributions
+ * @{
+ */
+
/**
* @brief A gamma continuous distribution for random numbers.
*
@@ -2422,6 +2460,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* p(x|\alpha,\beta) = \frac{1}{\beta\Gamma(\alpha)}
* (x/\beta)^{\alpha - 1} e^{-x/\beta}
* @f]
+ *
+ * @headerfile random
+ * @since C++11
*/
template
class gamma_distribution
@@ -2645,14 +2686,25 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
inline bool
operator!=(const std::gamma_distribution<_RealType>& __d1,
const std::gamma_distribution<_RealType>& __d2)
-{ return !(__d1 == __d2); }
+ { return !(__d1 == __d2); }
#endif
+ /// @} group random_distributions_poisson
+
+ /**
+ * @addtogroup random_distributions_normal Normal Distributions
+ * @ingroup random_distributions
+ * @{
+ */
+
/**
* @brief A chi_squared_distribution random
[committed] libstdc++: Improve doxygen docs for
Tested powerpc64le-linux. Docs tested on Fedora 37 with Doxygen 1.9.7
from current git master.
Pushed to trunk. I'll probably backport this too.
-- >8 --
libstdc++-v3/ChangeLog:
* include/bits/memory_resource.h: Improve doxygen comments.
* include/std/memory_resource: Likewise.
---
libstdc++-v3/include/bits/memory_resource.h | 12
libstdc++-v3/include/std/memory_resource| 63 +
2 files changed, 75 insertions(+)
diff --git a/libstdc++-v3/include/bits/memory_resource.h
b/libstdc++-v3/include/bits/memory_resource.h
index 1b9e51ddbbd..f12555d4215 100644
--- a/libstdc++-v3/include/bits/memory_resource.h
+++ b/libstdc++-v3/include/bits/memory_resource.h
@@ -53,6 +53,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
namespace pmr
{
/// Class memory_resource
+ /**
+ * @ingroup pmr
+ * @headerfile memory_resource
+ * @since C++17
+ */
class memory_resource
{
static constexpr size_t _S_max_align = alignof(max_align_t);
@@ -104,6 +109,13 @@ namespace pmr
#endif
// C++17 23.12.3 Class template polymorphic_allocator
+
+ /// Class template polymorphic_allocator
+ /**
+ * @ingroup pmr
+ * @headerfile memory_resource
+ * @since C++17
+ */
template
class polymorphic_allocator
{
diff --git a/libstdc++-v3/include/std/memory_resource
b/libstdc++-v3/include/std/memory_resource
index 00859262470..fdfc23c95ed 100644
--- a/libstdc++-v3/include/std/memory_resource
+++ b/libstdc++-v3/include/std/memory_resource
@@ -24,6 +24,9 @@
/** @file include/memory_resource
* This is a Standard C++ Library header.
+ *
+ * This header declares the @ref pmr (std::pmr) memory resources.
+ * @ingroup pmr
*/
#ifndef _GLIBCXX_MEMORY_RESOURCE
@@ -35,6 +38,25 @@
#if __cplusplus >= 201703L
+/**
+ * @defgroup pmr Polymorphic memory resources
+ *
+ * @anchor pmr
+ * @ingroup memory
+ * @since C++17
+ *
+ * Memory resources are classes that implement the `std::pmr::memory_resource`
+ * interface for allocating and deallocating memory. Unlike traditional C++
+ * allocators, memory resources are not value types and are used via pointers
+ * to the abstract base class. They are only responsible for allocating and
+ * deallocating, not for construction and destruction of objects. As a result,
+ * memory resources just allocate raw memory as type `void*` and are not
+ * templates that allocate/deallocate and construct/destroy a specific type.
+ *
+ * The class template `std::pmr::polymorphic_allocator` is an allocator that
+ * uses a memory resource for its allocations.
+ */
+
#include
#include // vector
#include // shared_mutex
@@ -63,6 +85,11 @@ namespace pmr
// Global memory resources
/// A pmr::memory_resource that uses `new` to allocate memory
+ /**
+ * @ingroup pmr
+ * @headerfile memory_resource
+ * @since C++17
+ */
[[nodiscard, __gnu__::__returns_nonnull__, __gnu__::__const__]]
memory_resource*
new_delete_resource() noexcept;
@@ -91,6 +118,11 @@ namespace pmr
class monotonic_buffer_resource;
/// Parameters for tuning a pool resource's behaviour.
+ /**
+ * @ingroup pmr
+ * @headerfile memory_resource
+ * @since C++17
+ */
struct pool_options
{
/** @brief Upper limit on number of blocks in a chunk.
@@ -152,6 +184,11 @@ namespace pmr
#ifdef _GLIBCXX_HAS_GTHREADS
/// A thread-safe memory resource that manages pools of fixed-size blocks.
+ /**
+ * @ingroup pmr
+ * @headerfile memory_resource
+ * @since C++17
+ */
class synchronized_pool_resource : public memory_resource
{
public:
@@ -218,6 +255,11 @@ namespace pmr
#endif
/// A non-thread-safe memory resource that manages pools of fixed-size
blocks.
+ /**
+ * @ingroup pmr
+ * @headerfile memory_resource
+ * @since C++17
+ */
class unsynchronized_pool_resource : public memory_resource
{
public:
@@ -275,6 +317,27 @@ namespace pmr
_Pool* _M_pools = nullptr;
};
+ /// A memory resource that allocates from a fixed-size buffer.
+ /**
+ * The main feature of a `pmr::monotonic_buffer_resource` is that its
+ * `do_deallocate` does nothing. This makes it very fast because there is no
+ * need to manage a free list, and every allocation simply returns a new
+ * block of memory, rather than searching for a suitably-sized free block.
+ * Because deallocating is a no-op, the amount of memory used by the resource
+ * only grows until `release()` (or the destructor) is called to return all
+ * memory to upstream.
+ *
+ * A `monotonic_buffer_resource` can be initialized with a buffer that
+ * will be used to satisfy all allocation requests, until the buffer is full.
+ * After that a new buffer will be allocated from the upstream resource.
+ * By using a stack buffer and `pmr::null_memory_resource()` as the upstream
+ * you can get a memory resource that only uses the stack and never
+ * dynamically allocates.
+ *
+ *
[committed] libstdc++: Improve doxygen docs for smart pointers
Signed-off-by: Jonathan Wakely
libstdc++-v3/ChangeLog:
* include/bits/shared_ptr.h: Add @since and @headerfile tags.
* include/bits/unique_ptr.h: Add @headerfile tags.
Tested powerpc64le-linux. Committed to trunk.
commit 30b300de8eb9a53c8ad8d80caf06e386e916bc66
Author: Jonathan Wakely
Date: Thu Aug 19 11:27:32 2021
libstdc++: Improve doxygen docs for smart pointers
Signed-off-by: Jonathan Wakely
libstdc++-v3/ChangeLog:
* include/bits/shared_ptr.h: Add @since and @headerfile tags.
* include/bits/unique_ptr.h: Add @headerfile tags.
diff --git a/libstdc++-v3/include/bits/shared_ptr.h
b/libstdc++-v3/include/bits/shared_ptr.h
index d5386ad535f..214ce20a878 100644
--- a/libstdc++-v3/include/bits/shared_ptr.h
+++ b/libstdc++-v3/include/bits/shared_ptr.h
@@ -102,6 +102,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief A smart pointer with reference-counted copy semantics.
+ * @headerfile memory
+ * @since C++11
*
* A `shared_ptr` object is either empty or _owns_ a pointer passed
* to the constructor. Copies of a `shared_ptr` share ownership of
@@ -139,6 +141,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#if __cplusplus >= 201703L
# define __cpp_lib_shared_ptr_weak_type 201606
/// The corresponding weak_ptr type for this shared_ptr
+ /// @since C++17
using weak_type = weak_ptr<_Tp>;
#endif
/**
@@ -266,6 +269,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __r A `shared_ptr`.
* @param __p A pointer that will remain valid while `*__r` is valid.
* @post `get() == __p && !__r.use_count() && !__r.get()`
+ * @since C++17
*
* This can be used to construct a `shared_ptr` to a sub-object
* of an object managed by an existing `shared_ptr`. The complete
@@ -607,6 +611,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#if __cplusplus >= 201703L
/// Convert type of `shared_ptr`, via `reinterpret_cast`
+ /// @since C++17
template
inline shared_ptr<_Tp>
reinterpret_pointer_cast(const shared_ptr<_Up>& __r) noexcept
@@ -620,6 +625,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 2996. Missing rvalue overloads for shared_ptr operations
/// Convert type of `shared_ptr` rvalue, via `static_cast`
+ /// @since C++20
template
inline shared_ptr<_Tp>
static_pointer_cast(shared_ptr<_Up>&& __r) noexcept
@@ -630,6 +636,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
/// Convert type of `shared_ptr` rvalue, via `const_cast`
+ /// @since C++20
template
inline shared_ptr<_Tp>
const_pointer_cast(shared_ptr<_Up>&& __r) noexcept
@@ -640,6 +647,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
/// Convert type of `shared_ptr` rvalue, via `dynamic_cast`
+ /// @since C++20
template
inline shared_ptr<_Tp>
dynamic_pointer_cast(shared_ptr<_Up>&& __r) noexcept
@@ -651,6 +659,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
/// Convert type of `shared_ptr` rvalue, via `reinterpret_cast`
+ /// @since C++20
template
inline shared_ptr<_Tp>
reinterpret_pointer_cast(shared_ptr<_Up>&& __r) noexcept
@@ -666,6 +675,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief A non-owning observer for a pointer owned by a shared_ptr
+ * @headerfile memory
+ * @since C++11
*
* A weak_ptr provides a safe alternative to a raw pointer when you want
* a non-owning reference to an object that is managed by a shared_ptr.
@@ -786,7 +797,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ };
/**
- * @brief Base class allowing use of member function shared_from_this.
+ * @brief Base class allowing use of the member function `shared_from_this`.
+ * @headerfile memory
+ * @since C++11
*/
template
class enable_shared_from_this
@@ -813,6 +826,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#if __cplusplus > 201402L || !defined(__STRICT_ANSI__) // c++1z or gnu++11
#define __cpp_lib_enable_shared_from_this 201603
+ /** @{
+ * Get a `weak_ptr` referring to the object that has `*this` as its base.
+ * @since C++17
+ */
weak_ptr<_Tp>
weak_from_this() noexcept
{ return this->_M_weak_this; }
@@ -820,6 +837,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
weak_ptr
weak_from_this() const noexcept
{ return this->_M_weak_this; }
+ /// @}
#endif
private:
diff --git a/libstdc++-v3/include/bits/unique_ptr.h
b/libstdc++-v3/include/bits/unique_ptr.h
index 023bd4d7f31..f34ca10ce65 100644
--- a/libstdc++-v3/include/bits/unique_ptr.h
+++ b/libstdc++-v3/include/bits/unique_ptr.h
@@ -240,6 +240,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 20.7.1.2 unique_ptr for single objects.
/// A move-only smart pointer that manages unique ownership of a resource.
+ /// @headerfile memory
/// @since C++11
template >
class unique_ptr
@@ -478,6 +479,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// DR 740 - omit specialization for array objects with
