From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2181) id 8CDE03858C74; Fri, 28 Apr 2023 12:07:38 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 8CDE03858C74 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1682683658; bh=UKJwAYUmdr0zG1J57DvoW5WsS6lqErC6rP2X0FfXImw=; h=From:To:Subject:Date:From; b=ZpkzvCHwGhN23BG+nQkt85SU//Pb6rmSwKp7dgGxn7xuOJNIJskv6lnJqoFH/f5Qc SKy2XMlYMxFGWZCE7c+p6q/8Gsi+wc2p5P822xIjXGigVXhdO2C4QDdf+c6HLkAHQt WHEg4q5gz5NnPP7FFWhq8yavG9MjWf9iFhvWosbY= MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="utf-8" From: Jonathan Wakely To: gcc-cvs@gcc.gnu.org, libstdc++-cvs@gcc.gnu.org Subject: [gcc r14-330] libstdc++: Improve doxygen docs for X-Act-Checkin: gcc X-Git-Author: Jonathan Wakely X-Git-Refname: refs/heads/master X-Git-Oldrev: 30f6aace7fe5c535af41a1f08ab00dc14fedf02d X-Git-Newrev: d711f8f81fc5f3a5a0420337f414bce93e1cad1e Message-Id: <20230428120738.8CDE03858C74@sourceware.org> Date: Fri, 28 Apr 2023 12:07:38 +0000 (GMT) List-Id: https://gcc.gnu.org/g:d711f8f81fc5f3a5a0420337f414bce93e1cad1e commit r14-330-gd711f8f81fc5f3a5a0420337f414bce93e1cad1e Author: Jonathan Wakely Date: Fri Apr 28 12:01:58 2023 +0100 libstdc++: Improve doxygen docs for 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. 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 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 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 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 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 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 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 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 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 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 class poisson_distribution @@ -4699,6 +4775,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * Range@f$[0, \infty]@f$ * Standard Deviation@f$\frac{1}{\lambda}@f$ * + * + * @headerfile random + * @since C++11 */ template 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 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 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 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 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 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 concept uniform_random_bit_generator = invocable<_Gen&> && unsigned_integral> @@ -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 class uniform_int_distribution