This is the mail archive of the
libstdc++@gcc.gnu.org
mailing list for the libstdc++ project.
Re: [v3] libstd++/42460
- From: Benjamin Kosnik <bkoz at redhat dot com>
- To: Benjamin Kosnik <bkoz at redhat dot com>
- Cc: libstdc++ at gcc dot gnu dot org, gcc-patches at gcc dot gnu dot org
- Date: Mon, 8 Feb 2010 20:55:10 -0800
- Subject: Re: [v3] libstd++/42460
- References: <20100204104322.122127d9@redhat.com>
more on this tip.
multi-line function markup is a no-go
fixes for ' quoting in regex
istream \\n fixes
With this, the remaining warnings look to be a stylesheet issue,
where the function markup is correct in HTML, but wrong in the man
pages.
-benjamin
2010-02-08 Benjamin Kosnik <bkoz@redhat.com>
* include/tr1_impl/regex: Fix quoting issues in doxygen markup.
* include/bits/random.h: Fix multi-line doxygen function markup.
2010-02-08 Matthias Klose <doko@debian.org>
* include/std/istream: Fix '\' quoting in doxygen markup.
Index: include/tr1_impl/regex
===================================================================
--- include/tr1_impl/regex (revision 156616)
+++ include/tr1_impl/regex (working copy)
@@ -135,9 +135,11 @@
* Specifies that the grammar recognized by the regular expression engine is
* that used by POSIX utility awk in IEEE Std 1003.1-2001. This option is
* identical to syntax_option_type extended, except that C-style escape
- * sequences are supported. These sequences are, explicitly, '\\', '\a',
- * '\b', '\f', '\n', '\r', '\t' , '\v', '\'', ''',
- * and '\ddd' (where ddd is one, two, or three octal digits).
+ * sequences are supported. These sequences are:
+ * \\\\, \\a, \\b, \\f,
+ * \\n, \\r, \\t , \\v,
+ * \\', ', and \\ddd
+ * (where ddd is one, two, or three octal digits).
*/
static const syntax_option_type awk = 1 << _S_awk;
@@ -202,26 +204,26 @@
/**
* The first character in the sequence [first, last) is treated as though it
- * is not at the beginning of a line, so the character '^' in the regular
+ * is not at the beginning of a line, so the character (^) in the regular
* expression shall not match [first, first).
*/
static const match_flag_type match_not_bol = 1 << _S_not_bol;
/**
* The last character in the sequence [first, last) is treated as though it
- * is not at the end of a line, so the character '$' in the regular
+ * is not at the end of a line, so the character ($) in the regular
* expression shall not match [last, last).
*/
static const match_flag_type match_not_eol = 1 << _S_not_eol;
/**
- * The expression '\b' is not matched against the sub-sequence
+ * The expression \\b is not matched against the sub-sequence
* [first,first).
*/
static const match_flag_type match_not_bow = 1 << _S_not_bow;
/**
- * The expression '\b' should not be matched against the sub-sequence
+ * The expression \\b should not be matched against the sub-sequence
* [last,last).
*/
static const match_flag_type match_not_eow = 1 << _S_not_eow;
@@ -363,7 +365,7 @@
static const error_type error_space(_S_error_space);
/**
- * One of '*?+{' was not preceded by a valid regular expression.
+ * One of <em>*?+{</em> was not preceded by a valid regular expression.
*/
static const error_type error_badrepeat(_S_error_badrepeat);
@@ -2532,7 +2534,7 @@
// [7.12.2] Class template regex_token_iterator
/**
- * Iterates over submatches in a range (or 'splits' a text string).
+ * Iterates over submatches in a range (or @a splits a text string).
*
* The purpose of this iterator is to enumerate all, or all specified,
* matches of a regular expression within a text range. The dereferenced
Index: include/std/istream
===================================================================
--- include/std/istream (revision 156616)
+++ include/std/istream (working copy)
@@ -327,7 +327,7 @@
* @param n Maximum number of characters to store in @a s.
* @return *this
*
- * Returns @c get(s,n,widen('\n')).
+ * Returns @c get(s,n,widen('\\n')).
*/
__istream_type&
get(char_type* __s, streamsize __n)
@@ -360,7 +360,7 @@
* @param sb A streambuf in which to store data.
* @return *this
*
- * Returns @c get(sb,widen('\n')).
+ * Returns @c get(sb,widen('\\n')).
*/
__istream_type&
get(__streambuf_type& __sb)
@@ -400,7 +400,7 @@
* @param n Maximum number of characters to extract.
* @return *this
*
- * Returns @c getline(s,n,widen('\n')).
+ * Returns @c getline(s,n,widen('\\n')).
*/
__istream_type&
getline(char_type* __s, streamsize __n)
Index: include/bits/random.h
===================================================================
--- include/bits/random.h (revision 156616)
+++ include/bits/random.h (working copy)
@@ -137,8 +137,11 @@
/**
* @brief A model of a linear congruential random number generator.
*
- * A random number generator that produces pseudorandom numbers using the
- * linear function @f$x_{i+1}\leftarrow(ax_{i} + c) \bmod m @f$.
+ * A random number generator that produces pseudorandom numbers via
+ * linear function:
+ * @f[
+ * x_{i+1}\leftarrow(ax_{i} + c) \bmod m
+ * @f]
*
* The template parameter @p _UIntType must be an unsigned integral type
* large enough to store values up to (__m-1). If the template parameter
@@ -146,7 +149,7 @@
* std::numeric_limits<_UIntType>::max() plus 1. Otherwise, the template
* parameters @p __a and @p __c must be less than @p __m.
*
- * The size of the state is @f$ 1 @f$.
+ * The size of the state is @f$1@f$.
*/
template<typename _UIntType, _UIntType __a, _UIntType __c, _UIntType __m>
class linear_congruential_engine
@@ -527,11 +530,13 @@
* generator, sometimes referred to as the SWC generator.
*
* A discrete random number generator that produces pseudorandom
- * numbers using @f$x_{i}\leftarrow(x_{i - s} - x_{i - r} -
- * carry_{i-1}) \bmod m @f$.
+ * numbers using:
+ * @f[
+ * x_{i}\leftarrow(x_{i - s} - x_{i - r} - carry_{i-1}) \bmod m
+ * @f]
*
- * The size of the state is @f$ r @f$
- * and the maximum period of the generator is @f$ m^r - m^s - 1 @f$.
+ * The size of the state is @f$r@f$
+ * and the maximum period of the generator is @f$(m^r - m^s - 1)@f$.
*
* @var _M_x The state of the generator. This is a ring buffer.
* @var _M_carry The carry.
@@ -578,7 +583,7 @@
{ seed<_Sseq>(__q); }
/**
- * @brief Seeds the initial state @f$ x_0 @f$ of the random number
+ * @brief Seeds the initial state @f$x_0@f$ of the random number
* generator.
*
* N1688[4.19] modifies this as follows. If @p __value == 0,
@@ -593,7 +598,7 @@
seed(result_type __sd = default_seed);
/**
- * @brief Seeds the initial state @f$ x_0 @f$ of the
+ * @brief Seeds the initial state @f$x_0@f$ of the
* % subtract_with_carry_engine random number generator.
*/
template<typename _Sseq, typename
@@ -1331,7 +1336,7 @@
minstd_rand0;
/**
- * An alternative LCR (Lehmer Generator function) .
+ * An alternative LCR (Lehmer Generator function).
*/
typedef linear_congruential_engine<uint_fast32_t, 48271UL, 0UL, 2147483647UL>
minstd_rand;
@@ -1364,9 +1369,6 @@
0xfff7eee000000000ULL, 43,
6364136223846793005ULL> mt19937_64;
- /**
- * .
- */
typedef subtract_with_carry_engine<uint_fast32_t, 24, 10, 24>
ranlux24_base;
@@ -1377,14 +1379,8 @@
typedef discard_block_engine<ranlux48_base, 389, 11> ranlux48;
- /**
- * .
- */
typedef shuffle_order_engine<minstd_rand0, 256> knuth_b;
- /**
- * .
- */
typedef minstd_rand0 default_random_engine;
/**
@@ -1809,8 +1805,10 @@
* @brief A normal continuous distribution for random numbers.
*
* The formula for the normal probability density function is
- * @f$ p(x|\mu,\sigma) = \frac{1}{\sigma \sqrt{2 \pi}}
- * e^{- \frac{{x - \mu}^ {2}}{2 \sigma ^ {2}} } @f$.
+ * @f[
+ * p(x|\mu,\sigma) = \frac{1}{\sigma \sqrt{2 \pi}}
+ * e^{- \frac{{x - \mu}^ {2}}{2 \sigma ^ {2}} }
+ * @f]
*/
template<typename _RealType = double>
class normal_distribution
@@ -1849,7 +1847,7 @@
public:
/**
- * Constructs a normal distribution with parameters @f$ mean @f$ and
+ * Constructs a normal distribution with parameters @f$mean@f$ and
* standard deviation.
*/
explicit
@@ -1964,8 +1962,10 @@
* @brief A lognormal_distribution random number distribution.
*
* The formula for the normal probability mass function is
- * @f$ p(x|m,s) = \frac{1}{sx\sqrt{2\pi}}
- * \exp{-\frac{(\ln{x} - m)^2}{2s^2}} @f$
+ * @f[
+ * p(x|m,s) = \frac{1}{sx\sqrt{2\pi}}
+ * \exp{-\frac{(\ln{x} - m)^2}{2s^2}}
+ * @f]
*/
template<typename _RealType = double>
class lognormal_distribution
@@ -2109,9 +2109,11 @@
/**
* @brief A gamma continuous distribution for random numbers.
*
- * The formula for the gamma probability density function is
- * @f$ p(x|\alpha,\beta) = \frac{1}{\beta\Gamma(\alpha)}
- * (x/\beta)^{\alpha - 1} e^{-x/\beta} @f$.
+ * The formula for the gamma probability density function is:
+ * @f[
+ * p(x|\alpha,\beta) = \frac{1}{\beta\Gamma(\alpha)}
+ * (x/\beta)^{\alpha - 1} e^{-x/\beta}
+ * @f]
*/
template<typename _RealType = double>
class gamma_distribution
@@ -2158,7 +2160,7 @@
public:
/**
* @brief Constructs a gamma distribution with parameters
- * @f$ \alpha @f$ and @f$ \beta @f$.
+ * @f$\alpha@f$ and @f$\beta@f$.
*/
explicit
gamma_distribution(_RealType __alpha_val = _RealType(1),
@@ -2179,14 +2181,14 @@
{ _M_nd.reset(); }
/**
- * @brief Returns the @f$ \alpha @f$ of the distribution.
+ * @brief Returns the @f$\alpha@f$ of the distribution.
*/
_RealType
alpha() const
{ return _M_param.alpha(); }
/**
- * @brief Returns the @f$ \beta @f$ of the distribution.
+ * @brief Returns the @f$\beta@f$ of the distribution.
*/
_RealType
beta() const
@@ -2271,7 +2273,7 @@
* @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$
+ * @f$p(x|n) = \frac{x^{(n/2) - 1}e^{-x/2}}{\Gamma(n/2) 2^{n/2}}@f$
*/
template<typename _RealType = double>
class chi_squared_distribution
@@ -2409,7 +2411,7 @@
* @brief A cauchy_distribution random number distribution.
*
* The formula for the normal probability mass function is
- * @f$ p(x|a,b) = (\pi b (1 + (\frac{x-a}{b})^2))^{-1} @f$
+ * @f$p(x|a,b) = (\pi b (1 + (\frac{x-a}{b})^2))^{-1}@f$
*/
template<typename _RealType = double>
class cauchy_distribution
@@ -2551,9 +2553,11 @@
* @brief A fisher_f_distribution random number distribution.
*
* The formula for the normal probability mass function is
- * @f$ p(x|m,n) = \frac{\Gamma((m+n)/2)}{\Gamma(m/2)\Gamma(n/2)}
+ * @f[
+ * p(x|m,n) = \frac{\Gamma((m+n)/2)}{\Gamma(m/2)\Gamma(n/2)}
* (\frac{m}{n})^{m/2} x^{(m/2)-1}
- * (1 + \frac{mx}{n})^{-(m+n)/2} @f$
+ * (1 + \frac{mx}{n})^{-(m+n)/2}
+ * @f]
*/
template<typename _RealType = double>
class fisher_f_distribution
@@ -2705,9 +2709,11 @@
/**
* @brief A student_t_distribution random number distribution.
*
- * The formula for the normal probability mass function is
- * @f$ 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$
+ * The formula for the normal probability mass function is:
+ * @f[
+ * 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]
*/
template<typename _RealType = double>
class student_t_distribution
@@ -2857,8 +2863,8 @@
/**
* @brief A Bernoulli random number distribution.
*
- * 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.
+ * 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.
*/
class bernoulli_distribution
{
@@ -2890,7 +2896,7 @@
* @brief Constructs a Bernoulli distribution with likelihood @p p.
*
* @param __p [IN] The likelihood of a true result being returned.
- * Must be in the interval @f$ [0, 1] @f$.
+ * Must be in the interval @f$[0, 1]@f$.
*/
explicit
bernoulli_distribution(double __p = 0.5)
@@ -3011,8 +3017,8 @@
* @brief A discrete binomial random number distribution.
*
* The formula for the binomial probability density function is
- * @f$ p(i|t,p) = \binom{n}{i} p^i (1 - p)^{t - i} @f$ where @f$ t @f$
- * and @f$ p @f$ are the parameters of the distribution.
+ * @f$p(i|t,p) = \binom{n}{i} p^i (1 - p)^{t - i}@f$ where @f$t@f$
+ * and @f$p@f$ are the parameters of the distribution.
*/
template<typename _IntType = int>
class binomial_distribution
@@ -3182,7 +3188,7 @@
* @brief A discrete geometric random number distribution.
*
* The formula for the geometric probability density function is
- * @f$ p(i|p) = (1 - p)p^{i-1} @f$ where @f$ p @f$ is the parameter of the
+ * @f$p(i|p) = (1 - p)p^{i-1}@f$ where @f$p@f$ is the parameter of the
* distribution.
*/
template<typename _IntType = int>
@@ -3328,8 +3334,8 @@
* @brief A negative_binomial_distribution random number distribution.
*
* 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.
+ * @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.
*/
template<typename _IntType = int>
class negative_binomial_distribution
@@ -3381,14 +3387,14 @@
{ _M_gd.reset(); }
/**
- * @brief Return the @f$ k @f$ parameter of the distribution.
+ * @brief Return the @f$k@f$ parameter of the distribution.
*/
_IntType
k() const
{ return _M_param.k(); }
/**
- * @brief Return the @f$ p @f$ parameter of the distribution.
+ * @brief Return the @f$p@f$ parameter of the distribution.
*/
double
p() const
@@ -3481,7 +3487,7 @@
* @brief A discrete Poisson random number distribution.
*
* 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
+ * @f$p(i|\mu) = \frac{\mu^i}{i!} e^{-\mu}@f$ where @f$\mu@f$ is the
* parameter of the distribution.
*/
template<typename _IntType = int>
@@ -3629,15 +3635,15 @@
* @brief An exponential continuous distribution for random numbers.
*
* The formula for the exponential probability density function is
- * @f$ p(x|\lambda) = \lambda e^{-\lambda x} @f$.
+ * @f$p(x|\lambda) = \lambda e^{-\lambda x}@f$.
*
* <table border=1 cellpadding=10 cellspacing=0>
* <caption align=top>Distribution Statistics</caption>
- * <tr><td>Mean</td><td>@f$ \frac{1}{\lambda} @f$</td></tr>
- * <tr><td>Median</td><td>@f$ \frac{\ln 2}{\lambda} @f$</td></tr>
- * <tr><td>Mode</td><td>@f$ zero @f$</td></tr>
+ * <tr><td>Mean</td><td>@f$\frac{1}{\lambda}@f$</td></tr>
+ * <tr><td>Median</td><td>@f$\frac{\ln 2}{\lambda}@f$</td></tr>
+ * <tr><td>Mode</td><td>@f$zero@f$</td></tr>
* <tr><td>Range</td><td>@f$[0, \infty]@f$</td></tr>
- * <tr><td>Standard Deviation</td><td>@f$ \frac{1}{\lambda} @f$</td></tr>
+ * <tr><td>Standard Deviation</td><td>@f$\frac{1}{\lambda}@f$</td></tr>
* </table>
*/
template<typename _RealType = double>
@@ -3672,7 +3678,7 @@
public:
/**
* @brief Constructs an exponential distribution with inverse scale
- * parameter @f$ \lambda @f$.
+ * parameter @f$\lambda@f$.
*/
explicit
exponential_distribution(const result_type& __lambda = result_type(1))
@@ -3781,9 +3787,11 @@
/**
* @brief A weibull_distribution random number distribution.
*
- * The formula for the normal probability density function is
- * @f$ p(x|\alpha,\beta) = \frac{\alpha}{\beta} (\frac{x}{\beta})^{\alpha-1}
- * \exp{(-(\frac{x}{\beta})^\alpha)} @f$.
+ * The formula for the normal probability density function is:
+ * @f[
+ * p(x|\alpha,\beta) = \frac{\alpha}{\beta} (\frac{x}{\beta})^{\alpha-1}
+ * \exp{(-(\frac{x}{\beta})^\alpha)}
+ * @f]
*/
template<typename _RealType = double>
class weibull_distribution
@@ -3837,14 +3845,14 @@
{ }
/**
- * @brief Return the @f$ a @f$ parameter of the distribution.
+ * @brief Return the @f$a@f$ parameter of the distribution.
*/
_RealType
a() const
{ return _M_param.a(); }
/**
- * @brief Return the @f$ b @f$ parameter of the distribution.
+ * @brief Return the @f$b@f$ parameter of the distribution.
*/
_RealType
b() const
@@ -3928,8 +3936,10 @@
* @brief A extreme_value_distribution random number distribution.
*
* The formula for the normal probability mass function is
- * @f$ p(x|a,b) = \frac{1}{b}
- * \exp( \frac{a-x}{b} - \exp(\frac{a-x}{b})) @f$
+ * @f[
+ * p(x|a,b) = \frac{1}{b}
+ * \exp( \frac{a-x}{b} - \exp(\frac{a-x}{b}))
+ * @f]
*/
template<typename _RealType = double>
class extreme_value_distribution
@@ -3983,14 +3993,14 @@
{ }
/**
- * @brief Return the @f$ a @f$ parameter of the distribution.
+ * @brief Return the @f$a@f$ parameter of the distribution.
*/
_RealType
a() const
{ return _M_param.a(); }
/**
- * @brief Return the @f$ b @f$ parameter of the distribution.
+ * @brief Return the @f$b@f$ parameter of the distribution.
*/
_RealType
b() const