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.

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