public inbox for gcc-cvs@sourceware.org
help / color / mirror / Atom feed
* [gcc r13-7269] libstdc++: Improve doxygen docs for <random>
@ 2023-04-28 13:10 Jonathan Wakely
0 siblings, 0 replies; only message in thread
From: Jonathan Wakely @ 2023-04-28 13:10 UTC (permalink / raw)
To: gcc-cvs, libstdc++-cvs
https://gcc.gnu.org/g:2f0e2f97d0129be4c2d17097c4a596c0dae9277d
commit r13-7269-g2f0e2f97d0129be4c2d17097c4a596c0dae9277d
Author: Jonathan Wakely <jwakely@redhat.com>
Date: Fri Apr 28 12:01:58 2023 +0100
libstdc++: Improve doxygen docs for <random>
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.
(cherry picked from commit d711f8f81fc5f3a5a0420337f414bce93e1cad1e)
Diff:
---
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<typename _UIntType, _UIntType __a, _UIntType __c, _UIntType __m>
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<typename _UIntType, size_t __w,
size_t __n, size_t __m, size_t __r,
@@ -697,6 +703,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* The size of the state is @f$r@f$
* and the maximum period of the generator is @f$(m^r - m^s - 1)@f$.
+ *
+ * @headerfile random
+ * @since C++11
*/
template<typename _UIntType, size_t __w, size_t __s, size_t __r>
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<typename _RandomNumberEngine, size_t __p, size_t __r>
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<typename _RandomNumberEngine, size_t __w, typename _UIntType>
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<typename _RandomNumberEngine, size_t __k>
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<typename _RealType = double>
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<typename _RealType = double>
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<typename _RealType = double>
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<typename _RealType = double>
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 number distribution.
*
* The formula for the normal probability mass function is
* @f$p(x|n) = \frac{x^{(n/2) - 1}e^{-x/2}}{\Gamma(n/2) 2^{n/2}}@f$
+ *
+ * @headerfile random
+ * @since C++11
*/
template<typename _RealType = double>
class chi_squared_distribution
@@ -2880,6 +2932,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* The formula for the normal probability mass function is
* @f$p(x|a,b) = (\pi b (1 + (\frac{x-a}{b})^2))^{-1}@f$
+ *
+ * @headerfile random
+ * @since C++11
*/
template<typename _RealType = double>
class cauchy_distribution
@@ -3092,6 +3147,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* (\frac{m}{n})^{m/2} x^{(m/2)-1}
* (1 + \frac{mx}{n})^{-(m+n)/2}
* @f]
+ *
+ * @headerfile random
+ * @since C++11
*/
template<typename _RealType = double>
class fisher_f_distribution
@@ -3328,6 +3386,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* p(x|n) = \frac{1}{\sqrt(n\pi)} \frac{\Gamma((n+1)/2)}{\Gamma(n/2)}
* (1 + \frac{x^2}{n}) ^{-(n+1)/2}
* @f]
+ *
+ * @headerfile random
+ * @since C++11
*/
template<typename _RealType = double>
class student_t_distribution
@@ -3559,6 +3620,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* Generates a sequence of true and false values with likelihood @f$p@f$
* that true will come up and @f$(1 - p)@f$ that false will appear.
+ *
+ * @headerfile random
+ * @since C++11
*/
class bernoulli_distribution
{
@@ -3779,6 +3843,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* The formula for the binomial probability density function is
* @f$p(i|t,p) = \binom{t}{i} p^i (1 - p)^{t - i}@f$ where @f$t@f$
* and @f$p@f$ are the parameters of the distribution.
+ *
+ * @headerfile random
+ * @since C++11
*/
template<typename _IntType = int>
class binomial_distribution
@@ -4022,6 +4089,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* The formula for the geometric probability density function is
* @f$p(i|p) = p(1 - p)^{i}@f$ where @f$p@f$ is the parameter of the
* distribution.
+ *
+ * @headerfile random
+ * @since C++11
*/
template<typename _IntType = int>
class geometric_distribution
@@ -4236,6 +4306,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* The formula for the negative binomial probability mass function is
* @f$p(i) = \binom{n}{i} p^i (1 - p)^{t - i}@f$ where @f$t@f$
* and @f$p@f$ are the parameters of the distribution.
+ *
+ * @headerfile random
+ * @since C++11
*/
template<typename _IntType = int>
class negative_binomial_distribution
@@ -4470,6 +4543,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* The formula for the Poisson probability density function is
* @f$p(i|\mu) = \frac{\mu^i}{i!} e^{-\mu}@f$ where @f$\mu@f$ is the
* parameter of the distribution.
+ *
+ * @headerfile random
+ * @since C++11
*/
template<typename _IntType = int>
class poisson_distribution
@@ -4699,6 +4775,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* <tr><td>Range</td><td>@f$[0, \infty]@f$</td></tr>
* <tr><td>Standard Deviation</td><td>@f$\frac{1}{\lambda}@f$</td></tr>
* </table>
+ *
+ * @headerfile random
+ * @since C++11
*/
template<typename _RealType = double>
class exponential_distribution
@@ -4918,6 +4997,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* p(x|\alpha,\beta) = \frac{\alpha}{\beta} (\frac{x}{\beta})^{\alpha-1}
* \exp{(-(\frac{x}{\beta})^\alpha)}
* @f]
+ *
+ * @headerfile random
+ * @since C++11
*/
template<typename _RealType = double>
class weibull_distribution
@@ -5132,6 +5214,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* p(x|a,b) = \frac{1}{b}
* \exp( \frac{a-x}{b} - \exp(\frac{a-x}{b}))
* @f]
+ *
+ * @headerfile random
+ * @since C++11
*/
template<typename _RealType = double>
class extreme_value_distribution
@@ -5337,12 +5422,23 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
operator>>(std::basic_istream<_CharT, _Traits>& __is,
std::extreme_value_distribution<_RealType>& __x);
+ /// @} group random_distributions_poisson
+
+ /**
+ * @addtogroup random_distributions_sampling Sampling Distributions
+ * @ingroup random_distributions
+ * @{
+ */
/**
* @brief A discrete_distribution random number distribution.
*
- * The formula for the discrete probability mass function is
+ * This distribution produces random numbers @f$ i, 0 \leq i < n @f$,
+ * distributed according to the probability mass function
+ * @f$ p(i | p_0, ..., p_{n-1}) = p_i @f$.
*
+ * @headerfile random
+ * @since C++11
*/
template<typename _IntType = int>
class discrete_distribution
@@ -5579,8 +5675,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief A piecewise_constant_distribution random number distribution.
*
- * The formula for the piecewise constant probability mass function is
+ * This distribution produces random numbers @f$ x, b_0 \leq x < b_n @f$,
+ * uniformly distributed over each subinterval @f$ [b_i, b_{i+1}) @f$
+ * according to the probability mass function
+ * @f[
+ * p(x | b_0, ..., b_n, \rho_0, ..., \rho_{n-1})
+ * = \rho_i \cdot \frac{b_{i+1} - x}{b_{i+1} - b_i}
+ * + \rho_{i+1} \cdot \frac{ x - b_i}{b_{i+1} - b_i}
+ * @f]
+ * for @f$ b_i \leq x < b_{i+1} @f$.
*
+ * @headerfile random
+ * @since C++11
*/
template<typename _RealType = double>
class piecewise_constant_distribution
@@ -5853,8 +5959,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief A piecewise_linear_distribution random number distribution.
*
- * The formula for the piecewise linear probability mass function is
+ * This distribution produces random numbers @f$ x, b_0 \leq x < b_n @f$,
+ * distributed over each subinterval @f$ [b_i, b_{i+1}) @f$
+ * according to the probability mass function
+ * @f$ p(x | b_0, ..., b_n, \rho_0, ..., \rho_n) = \rho_i @f$,
+ * for @f$ b_i \leq x < b_{i+1} @f$.
*
+ * @headerfile random
+ * @since C++11
*/
template<typename _RealType = double>
class piecewise_linear_distribution
@@ -6126,7 +6238,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return !(__d1 == __d2); }
#endif
- /// @} group random_distributions_poisson
+ /// @} group random_distributions_sampling
/// @} *group random_distributions
@@ -6139,6 +6251,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief The seed_seq class generates sequences of seeds for random
* number generators.
+ *
+ * @headerfile random
+ * @since C++11
*/
class seed_seq
{
diff --git a/libstdc++-v3/include/bits/uniform_int_dist.h b/libstdc++-v3/include/bits/uniform_int_dist.h
index 5776e5deb1a..7ccf930a6d4 100644
--- a/libstdc++-v3/include/bits/uniform_int_dist.h
+++ b/libstdc++-v3/include/bits/uniform_int_dist.h
@@ -44,6 +44,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#ifdef __cpp_lib_concepts
/// Requirements for a uniform random bit generator.
+ /**
+ * @ingroup random_distributions_uniform
+ * @headerfile random
+ * @since C++20
+ */
template<typename _Gen>
concept uniform_random_bit_generator
= invocable<_Gen&> && unsigned_integral<invoke_result_t<_Gen&>>
@@ -55,6 +60,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
};
#endif
+ /// @cond undocumented
namespace __detail
{
// Determine whether number is a power of two.
@@ -67,11 +73,16 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return ((__x - 1) & __x) == 0;
}
}
+ /// @endcond
/**
* @brief Uniform discrete distribution for random numbers.
* A discrete random distribution on the range @f$[min, max]@f$ with equal
* probability throughout the range.
+ *
+ * @ingroup random_distributions_uniform
+ * @headerfile random
+ * @since C++11
*/
template<typename _IntType = int>
class uniform_int_distribution
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2023-04-28 13:10 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-04-28 13:10 [gcc r13-7269] libstdc++: Improve doxygen docs for <random> 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).