Merge branch 'gh-5685', docstring cleanups for mtrand.pyx.

* gh-5685:
  DOC: Some cleanups of mtrand.pyx docstrings.
  DOC: Minor edits to docstrings to improve consistency in the module
  DOC: Incremental improvement in random module docstrings

1 files changed, 279 insertions, 240 deletions

diff --git a/numpy/random/mtrand/mtrand.pyx b/numpy/random/mtrand/mtrand.pyx
index 42721e762..c4927a3f3 100644
--- a/numpy/random/mtrand/mtrand.pyx
+++ b/numpy/random/mtrand/mtrand.pyx
@@ -634,7 +634,7 @@ cdef class RandomState:
         ----------
         seed : int or array_like, optional
             Seed for `RandomState`.
-            Must be convertable to 32 bit unsigned integers.
+            Must be convertible to 32 bit unsigned integers.
 
         See Also
         --------
@@ -1252,8 +1252,8 @@ cdef class RandomState:
         olow = <ndarray>PyArray_FROM_OTF(low, NPY_DOUBLE, NPY_ARRAY_ALIGNED)
         ohigh = <ndarray>PyArray_FROM_OTF(high, NPY_DOUBLE, NPY_ARRAY_ALIGNED)
         temp = np.subtract(ohigh, olow)
-        Py_INCREF(temp) # needed to get around Pyrex's automatic reference-counting
-                        #  rules because EnsureArray steals a reference
+        Py_INCREF(temp)  # needed to get around Pyrex's automatic reference-counting
+                         # rules because EnsureArray steals a reference
         odiff = <ndarray>PyArray_EnsureArray(temp)
         return cont2_array(self.internal_state, rk_uniform, size, olow, odiff,
                            self.lock)
@@ -1443,7 +1443,7 @@ cdef class RandomState:
         """
         standard_normal(size=None)
 
-        Returns samples from a Standard Normal distribution (mean=0, stdev=1).
+        Draw samples from a standard Normal distribution (mean=0, stdev=1).
 
         Parameters
         ----------
@@ -1511,22 +1511,22 @@ cdef class RandomState:
         .. math:: p(x) = \\frac{1}{\\sqrt{ 2 \\pi \\sigma^2 }}
                          e^{ - \\frac{ (x - \\mu)^2 } {2 \\sigma^2} },
 
-        where :math:`\\mu` is the mean and :math:`\\sigma` the standard deviation.
-        The square of the standard deviation, :math:`\\sigma^2`, is called the
-        variance.
+        where :math:`\\mu` is the mean and :math:`\\sigma` the standard
+        deviation. The square of the standard deviation, :math:`\\sigma^2`,
+        is called the variance.
 
         The function has its peak at the mean, and its "spread" increases with
         the standard deviation (the function reaches 0.607 times its maximum at
         :math:`x + \\sigma` and :math:`x - \\sigma` [2]_).  This implies that
-        `numpy.random.normal` is more likely to return samples lying close to the
-        mean, rather than those far away.
+        `numpy.random.normal` is more likely to return samples lying close to
+        the mean, rather than those far away.
 
         References
         ----------
         .. [1] Wikipedia, "Normal distribution",
                http://en.wikipedia.org/wiki/Normal_distribution
-        .. [2] P. R. Peebles Jr., "Central Limit Theorem" in "Probability, Random
-               Variables and Random Signal Principles", 4th ed., 2001,
+        .. [2] P. R. Peebles Jr., "Central Limit Theorem" in "Probability,
+               Random Variables and Random Signal Principles", 4th ed., 2001,
                pp. 51, 51, 125.
 
         Examples
@@ -1579,7 +1579,7 @@ cdef class RandomState:
         """
         beta(a, b, size=None)
 
-        The Beta distribution over ``[0, 1]``.
+        Draw samples from a Beta distribution.
 
         The Beta distribution is a special case of the Dirichlet distribution,
         and is related to the Gamma distribution.  It has the probability
@@ -1641,7 +1641,7 @@ cdef class RandomState:
         """
         exponential(scale=1.0, size=None)
 
-        Exponential distribution.
+        Draw samples from an exponential distribution.
 
         Its probability density function is
 
@@ -1688,7 +1688,8 @@ cdef class RandomState:
 
         PyErr_Clear()
 
-        oscale = <ndarray> PyArray_FROM_OTF(scale, NPY_DOUBLE, NPY_ARRAY_ALIGNED)
+        oscale = <ndarray> PyArray_FROM_OTF(scale, NPY_DOUBLE,
+                                            NPY_ARRAY_ALIGNED)
         if np.any(np.less_equal(oscale, 0.0)):
             raise ValueError("scale <= 0")
         return cont1_array(self.internal_state, rk_exponential, size, oscale,
@@ -1729,7 +1730,7 @@ cdef class RandomState:
         """
         standard_gamma(shape, size=None)
 
-        Draw samples from a Standard Gamma distribution.
+        Draw samples from a standard Gamma distribution.
 
         Samples are drawn from a Gamma distribution with specified parameters,
         shape (sometimes designated "k") and scale=1.
@@ -1800,10 +1801,12 @@ cdef class RandomState:
         if not PyErr_Occurred():
             if fshape <= 0:
                 raise ValueError("shape <= 0")
-            return cont1_array_sc(self.internal_state, rk_standard_gamma, size, fshape, self.lock)
+            return cont1_array_sc(self.internal_state, rk_standard_gamma,
+                                  size, fshape, self.lock)
 
         PyErr_Clear()
-        oshape = <ndarray> PyArray_FROM_OTF(shape, NPY_DOUBLE, NPY_ARRAY_ALIGNED)
+        oshape = <ndarray> PyArray_FROM_OTF(shape, NPY_DOUBLE,
+                                            NPY_ARRAY_ALIGNED)
         if np.any(np.less_equal(oshape, 0.0)):
             raise ValueError("shape <= 0")
         return cont1_array(self.internal_state, rk_standard_gamma, size,
@@ -1907,11 +1910,12 @@ cdef class RandomState:
         """
         f(dfnum, dfden, size=None)
 
-        Draw samples from a F distribution.
+        Draw samples from an F distribution.
 
         Samples are drawn from an F distribution with specified parameters,
-        `dfnum` (degrees of freedom in numerator) and `dfden` (degrees of freedom
-        in denominator), where both parameters should be greater than zero.
+        `dfnum` (degrees of freedom in numerator) and `dfden` (degrees of
+        freedom in denominator), where both parameters should be greater than
+        zero.
 
         The random variate of the F distribution (also known as the
         Fisher distribution) is a continuous probability distribution
@@ -1958,7 +1962,8 @@ cdef class RandomState:
 
         Examples
         --------
-        An example from Glantz[1], pp 47-40.
+        An example from Glantz[1], pp 47-40:
+
         Two groups, children of diabetics (25 people) and children from people
         without diabetes (25 controls). Fasting blood glucose was measured,
         case group had a mean value of 86.1, controls had a mean value of
@@ -2046,11 +2051,11 @@ cdef class RandomState:
 
         References
         ----------
-        Weisstein, Eric W. "Noncentral F-Distribution." From MathWorld--A Wolfram
-        Web Resource.  http://mathworld.wolfram.com/NoncentralF-Distribution.html
-
-        Wikipedia, "Noncentral F distribution",
-        http://en.wikipedia.org/wiki/Noncentral_F-distribution
+        .. [1] Weisstein, Eric W. "Noncentral F-Distribution."
+               From MathWorld--A Wolfram Web Resource.
+               http://mathworld.wolfram.com/NoncentralF-Distribution.html
+        .. [2] Wikipedia, "Noncentral F distribution",
+               http://en.wikipedia.org/wiki/Noncentral_F-distribution
 
         Examples
         --------
@@ -2157,8 +2162,8 @@ cdef class RandomState:
 
         References
         ----------
-        `NIST/SEMATECH e-Handbook of Statistical Methods
-        <http://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm>`_
+        .. [1] NIST "Engineering Statistics Handbook"
+               http://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm
 
         Examples
         --------
@@ -2206,23 +2211,25 @@ cdef class RandomState:
 
         Notes
         -----
-        The probability density function for the noncentral Chi-square distribution
-        is
+        The probability density function for the noncentral Chi-square
+        distribution is
 
         .. math:: P(x;df,nonc) = \\sum^{\\infty}_{i=0}
-                               \\frac{e^{-nonc/2}(nonc/2)^{i}}{i!}P_{Y_{df+2i}}(x),
+                               \\frac{e^{-nonc/2}(nonc/2)^{i}}{i!}
+                               \\P_{Y_{df+2i}}(x),
 
         where :math:`Y_{q}` is the Chi-square with q degrees of freedom.
 
-        In Delhi (2007), it is noted that the noncentral chi-square is useful in
-        bombing and coverage problems, the probability of killing the point target
-        given by the noncentral chi-squared distribution.
+        In Delhi (2007), it is noted that the noncentral chi-square is
+        useful in bombing and coverage problems, the probability of
+        killing the point target given by the noncentral chi-squared
+        distribution.
 
         References
         ----------
-        .. [1] Delhi, M.S. Holla, "On a noncentral chi-square distribution in the
-               analysis of weapon systems effectiveness", Metrika, Volume 15,
-               Number 1 / December, 1970.
+        .. [1] Delhi, M.S. Holla, "On a noncentral chi-square distribution in
+               the analysis of weapon systems effectiveness", Metrika,
+               Volume 15, Number 1 / December, 1970.
         .. [2] Wikipedia, "Noncentral chi-square distribution"
                http://en.wikipedia.org/wiki/Noncentral_chi-square_distribution
 
@@ -2282,7 +2289,7 @@ cdef class RandomState:
         """
         standard_cauchy(size=None)
 
-        Standard Cauchy distribution with mode = 0.
+        Draw samples from a standard Cauchy distribution with mode = 0.
 
         Also known as the Lorentz distribution.
 
@@ -2346,10 +2353,11 @@ cdef class RandomState:
         """
         standard_t(df, size=None)
 
-        Standard Student's t distribution with df degrees of freedom.
+        Draw samples from a standard Student's t distribution with `df` degrees
+        of freedom.
 
-        A special case of the hyperbolic distribution.
-        As `df` gets large, the result resembles that of the standard normal
+        A special case of the hyperbolic distribution.  As `df` gets
+        large, the result resembles that of the standard normal
         distribution (`standard_normal`).
 
         Parameters
@@ -2373,15 +2381,15 @@ cdef class RandomState:
         .. math:: P(x, df) = \\frac{\\Gamma(\\frac{df+1}{2})}{\\sqrt{\\pi df}
                   \\Gamma(\\frac{df}{2})}\\Bigl( 1+\\frac{x^2}{df} \\Bigr)^{-(df+1)/2}
 
-        The t test is based on an assumption that the data come from a Normal
-        distribution. The t test provides a way to test whether the sample mean
-        (that is the mean calculated from the data) is a good estimate of the true
-        mean.
+        The t test is based on an assumption that the data come from a
+        Normal distribution. The t test provides a way to test whether
+        the sample mean (that is the mean calculated from the data) is
+        a good estimate of the true mean.
 
-        The derivation of the t-distribution was forst published in 1908 by William
-        Gisset while working for the Guinness Brewery in Dublin. Due to proprietary
-        issues, he had to publish under a pseudonym, and so he used the name
-        Student.
+        The derivation of the t-distribution was first published in
+        1908 by William Gisset while working for the Guinness Brewery
+        in Dublin. Due to proprietary issues, he had to publish under
+        a pseudonym, and so he used the name Student.
 
         References
         ----------
@@ -2498,11 +2506,11 @@ cdef class RandomState:
 
         References
         ----------
-        Abramowitz, M. and Stegun, I. A. (ed.), *Handbook of Mathematical
-        Functions*, New York: Dover, 1965.
-
-        von Mises, R., *Mathematical Theory of Probability and Statistics*,
-        New York: Academic Press, 1964.
+        .. [1] Abramowitz, M. and Stegun, I. A. (Eds.). "Handbook of
+               Mathematical Functions with Formulas, Graphs, and Mathematical
+               Tables, 9th printing," New York: Dover, 1972.
+        .. [2] von Mises, R., "Mathematical Theory of Probability
+               and Statistics", New York: Academic Press, 1964.
 
         Examples
         --------
@@ -2537,7 +2545,8 @@ cdef class RandomState:
         PyErr_Clear()
 
         omu = <ndarray> PyArray_FROM_OTF(mu, NPY_DOUBLE, NPY_ARRAY_ALIGNED)
-        okappa = <ndarray> PyArray_FROM_OTF(kappa, NPY_DOUBLE, NPY_ARRAY_ALIGNED)
+        okappa = <ndarray> PyArray_FROM_OTF(kappa, NPY_DOUBLE,
+                                            NPY_ARRAY_ALIGNED)
         if np.any(np.less(okappa, 0.0)):
             raise ValueError("kappa < 0")
         return cont2_array(self.internal_state, rk_vonmises, size, omu, okappa,
@@ -2547,21 +2556,25 @@ cdef class RandomState:
         """
         pareto(a, size=None)
 
-        Draw samples from a Pareto II or Lomax distribution with specified shape.
-
-        The Lomax or Pareto II distribution is a shifted Pareto distribution. The
-        classical Pareto distribution can be obtained from the Lomax distribution
-        by adding 1 and multiplying by the scale parameter ``m`` (see Notes).
-        The smallest value of the Lomax distribution is zero while for the
-        classical Pareto distribution it is ``mu``, where the standard Pareto
-        distribution has location ``mu = 1``.  Lomax can also be considered as a
-        simplified version of the Generalized Pareto distribution (available in
-        SciPy), with the scale set to one and the location set to zero.
-
-        The Pareto distribution must be greater than zero, and is unbounded above.
-        It is also known as the "80-20 rule".  In this distribution, 80 percent of
-        the weights are in the lowest 20 percent of the range, while the other 20
-        percent fill the remaining 80 percent of the range.
+        Draw samples from a Pareto II or Lomax distribution with
+        specified shape.
+
+        The Lomax or Pareto II distribution is a shifted Pareto
+        distribution. The classical Pareto distribution can be
+        obtained from the Lomax distribution by adding 1 and
+        multiplying by the scale parameter ``m`` (see Notes).  The
+        smallest value of the Lomax distribution is zero while for the
+        classical Pareto distribution it is ``mu``, where the standard
+        Pareto distribution has location ``mu = 1``.  Lomax can also
+        be considered as a simplified version of the Generalized
+        Pareto distribution (available in SciPy), with the scale set
+        to one and the location set to zero.
+
+        The Pareto distribution must be greater than zero, and is
+        unbounded above.  It is also known as the "80-20 rule".  In
+        this distribution, 80 percent of the weights are in the lowest
+        20 percent of the range, while the other 20 percent fill the
+        remaining 80 percent of the range.
 
         Parameters
         ----------
@@ -2587,14 +2600,16 @@ cdef class RandomState:
 
         where :math:`a` is the shape and :math:`m` the scale.
 
-        The Pareto distribution, named after the Italian economist Vilfredo Pareto,
-        is a power law probability distribution useful in many real world problems.
-        Outside the field of economics it is generally referred to as the Bradford
-        distribution. Pareto developed the distribution to describe the
-        distribution of wealth in an economy.  It has also found use in insurance,
-        web page access statistics, oil field sizes, and many other problems,
-        including the download frequency for projects in Sourceforge [1]_.  It is
-        one of the so-called "fat-tailed" distributions.
+        The Pareto distribution, named after the Italian economist
+        Vilfredo Pareto, is a power law probability distribution
+        useful in many real world problems.  Outside the field of
+        economics it is generally referred to as the Bradford
+        distribution. Pareto developed the distribution to describe
+        the distribution of wealth in an economy.  It has also found
+        use in insurance, web page access statistics, oil field sizes,
+        and many other problems, including the download frequency for
+        projects in Sourceforge [1]_.  It is one of the so-called
+        "fat-tailed" distributions.
 
 
         References
@@ -2645,7 +2660,7 @@ cdef class RandomState:
         """
         weibull(a, size=None)
 
-        Weibull distribution.
+        Draw samples from a Weibull distribution.
 
         Draw samples from a 1-parameter Weibull distribution with the given
         shape parameter `a`.
@@ -2666,6 +2681,10 @@ cdef class RandomState:
             ``m * n * k`` samples are drawn.  Default is None, in which case a
             single value is returned.
 
+        Returns
+        -------
+        samples : ndarray
+
         See Also
         --------
         scipy.stats.distributions.weibull_max
@@ -2675,10 +2694,11 @@ cdef class RandomState:
 
         Notes
         -----
-        The Weibull (or Type III asymptotic extreme value distribution for smallest
-        values, SEV Type III, or Rosin-Rammler distribution) is one of a class of
-        Generalized Extreme Value (GEV) distributions used in modeling extreme
-        value problems.  This class includes the Gumbel and Frechet distributions.
+        The Weibull (or Type III asymptotic extreme value distribution
+        for smallest values, SEV Type III, or Rosin-Rammler
+        distribution) is one of a class of Generalized Extreme Value
+        (GEV) distributions used in modeling extreme value problems.
+        This class includes the Gumbel and Frechet distributions.
 
         The probability density for the Weibull distribution is
 
@@ -2695,12 +2715,13 @@ cdef class RandomState:
 
         References
         ----------
-        .. [1] Waloddi Weibull, Professor, Royal Technical University, Stockholm,
+        .. [1] Waloddi Weibull, Royal Technical University, Stockholm,
                1939 "A Statistical Theory Of The Strength Of Materials",
                Ingeniorsvetenskapsakademiens Handlingar Nr 151, 1939,
                Generalstabens Litografiska Anstalts Forlag, Stockholm.
-        .. [2] Waloddi Weibull, 1951 "A Statistical Distribution Function of Wide
-               Applicability",  Journal Of Applied Mechanics ASME Paper.
+        .. [2] Waloddi Weibull, "A Statistical Distribution Function of
+               Wide Applicability", Journal Of Applied Mechanics ASME Paper
+               1951.
         .. [3] Wikipedia, "Weibull distribution",
                http://en.wikipedia.org/wiki/Weibull_distribution
 
@@ -2770,7 +2791,7 @@ cdef class RandomState:
         Raises
         ------
         ValueError
-            If a<1.
+            If a < 1.
 
         Notes
         -----
@@ -2789,10 +2810,10 @@ cdef class RandomState:
         ----------
         .. [1] Christian Kleiber, Samuel Kotz, "Statistical size distributions
                in economics and actuarial sciences", Wiley, 2003.
-        .. [2] Heckert, N. A. and Filliben, James J. (2003). NIST Handbook 148:
+        .. [2] Heckert, N. A. and Filliben, James J. "NIST Handbook 148:
                Dataplot Reference Manual, Volume 2: Let Subcommands and Library
-               Functions", National Institute of Standards and Technology Handbook
-               Series, June 2003.
+               Functions", National Institute of Standards and Technology
+               Handbook Series, June 2003.
                http://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/powpdf.pdf
 
         Examples
@@ -2869,15 +2890,19 @@ cdef class RandomState:
 
         Parameters
         ----------
-        loc : float
+        loc : float, optional
             The position, :math:`\\mu`, of the distribution peak.
-        scale : float
+        scale : float, optional
             :math:`\\lambda`, the exponential decay.
         size : int or tuple of ints, optional
             Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
             ``m * n * k`` samples are drawn.  Default is None, in which case a
             single value is returned.
 
+        Returns
+        -------
+        samples : ndarray or float
+
         Notes
         -----
         It has the probability density function
@@ -2885,28 +2910,24 @@ cdef class RandomState:
         .. math:: f(x; \\mu, \\lambda) = \\frac{1}{2\\lambda}
                                        \\exp\\left(-\\frac{|x - \\mu|}{\\lambda}\\right).
 
-        The first law of Laplace, from 1774, states that the frequency of an error
-        can be expressed as an exponential function of the absolute magnitude of
-        the error, which leads to the Laplace distribution. For many problems in
-        Economics and Health sciences, this distribution seems to model the data
-        better than the standard Gaussian distribution
-
+        The first law of Laplace, from 1774, states that the frequency
+        of an error can be expressed as an exponential function of the
+        absolute magnitude of the error, which leads to the Laplace
+        distribution. For many problems in economics and health
+        sciences, this distribution seems to model the data better
+        than the standard Gaussian distribution.
 
         References
         ----------
-        .. [1] Abramowitz, M. and Stegun, I. A. (Eds.). Handbook of Mathematical
-               Functions with Formulas, Graphs, and Mathematical Tables, 9th
-               printing.  New York: Dover, 1972.
-
-        .. [2] The Laplace distribution and generalizations
-               By Samuel Kotz, Tomasz J. Kozubowski, Krzysztof Podgorski,
-               Birkhauser, 2001.
-
+        .. [1] Abramowitz, M. and Stegun, I. A. (Eds.). "Handbook of
+               Mathematical Functions with Formulas, Graphs, and Mathematical
+               Tables, 9th printing," New York: Dover, 1972.
+        .. [2] Kotz, Samuel, et. al. "The Laplace Distribution and
+               Generalizations, " Birkhauser, 2001.
         .. [3] Weisstein, Eric W. "Laplace Distribution."
                From MathWorld--A Wolfram Web Resource.
                http://mathworld.wolfram.com/LaplaceDistribution.html
-
-        .. [4] Wikipedia, "Laplace distribution",
+        .. [4] Wikipedia, "Laplace Distribution",
                http://en.wikipedia.org/wiki/Laplace_distribution
 
         Examples
@@ -2955,11 +2976,11 @@ cdef class RandomState:
         """
         gumbel(loc=0.0, scale=1.0, size=None)
 
-        Gumbel distribution.
+        Draw samples from a Gumbel distribution.
 
-        Draw samples from a Gumbel distribution with specified location and scale.
-        For more information on the Gumbel distribution, see Notes and References
-        below.
+        Draw samples from a Gumbel distribution with specified location and
+        scale.  For more information on the Gumbel distribution, see
+        Notes and References below.
 
         Parameters
         ----------
@@ -2974,59 +2995,54 @@ cdef class RandomState:
 
         Returns
         -------
-        out : ndarray
-            The samples
+        samples : ndarray or scalar
 
         See Also
         --------
         scipy.stats.gumbel_l
         scipy.stats.gumbel_r
         scipy.stats.genextreme
-            probability density function, distribution, or cumulative density
-            function, etc. for each of the above
         weibull
 
         Notes
         -----
-        The Gumbel (or Smallest Extreme Value (SEV) or the Smallest Extreme Value
-        Type I) distribution is one of a class of Generalized Extreme Value (GEV)
-        distributions used in modeling extreme value problems.  The Gumbel is a
-        special case of the Extreme Value Type I distribution for maximums from
-        distributions with "exponential-like" tails.
+        The Gumbel (or Smallest Extreme Value (SEV) or the Smallest Extreme
+        Value Type I) distribution is one of a class of Generalized Extreme
+        Value (GEV) distributions used in modeling extreme value problems.
+        The Gumbel is a special case of the Extreme Value Type I distribution
+        for maximums from distributions with "exponential-like" tails.
 
         The probability density for the Gumbel distribution is
 
         .. math:: p(x) = \\frac{e^{-(x - \\mu)/ \\beta}}{\\beta} e^{ -e^{-(x - \\mu)/
                   \\beta}},
 
-        where :math:`\\mu` is the mode, a location parameter, and :math:`\\beta` is
-        the scale parameter.
+        where :math:`\\mu` is the mode, a location parameter, and
+        :math:`\\beta` is the scale parameter.
 
         The Gumbel (named for German mathematician Emil Julius Gumbel) was used
         very early in the hydrology literature, for modeling the occurrence of
-        flood events. It is also used for modeling maximum wind speed and rainfall
-        rates.  It is a "fat-tailed" distribution - the probability of an event in
-        the tail of the distribution is larger than if one used a Gaussian, hence
-        the surprisingly frequent occurrence of 100-year floods. Floods were
-        initially modeled as a Gaussian process, which underestimated the frequency
-        of extreme events.
-
+        flood events. It is also used for modeling maximum wind speed and
+        rainfall rates.  It is a "fat-tailed" distribution - the probability of
+        an event in the tail of the distribution is larger than if one used a
+        Gaussian, hence the surprisingly frequent occurrence of 100-year
+        floods. Floods were initially modeled as a Gaussian process, which
+        underestimated the frequency of extreme events.
 
         It is one of a class of extreme value distributions, the Generalized
         Extreme Value (GEV) distributions, which also includes the Weibull and
         Frechet.
 
-        The function has a mean of :math:`\\mu + 0.57721\\beta` and a variance of
-        :math:`\\frac{\\pi^2}{6}\\beta^2`.
+        The function has a mean of :math:`\\mu + 0.57721\\beta` and a variance
+        of :math:`\\frac{\\pi^2}{6}\\beta^2`.
 
         References
         ----------
-        Gumbel, E. J., *Statistics of Extremes*, New York: Columbia University
-        Press, 1958.
-
-        Reiss, R.-D. and Thomas, M., *Statistical Analysis of Extreme Values from
-        Insurance, Finance, Hydrology and Other Fields*, Basel: Birkhauser Verlag,
-        2001.
+        .. [1] Gumbel, E. J., "Statistics of Extremes,"
+               New York: Columbia University Press, 1958.
+        .. [2] Reiss, R.-D. and Thomas, M., "Statistical Analysis of Extreme
+               Values from Insurance, Finance, Hydrology and Other Fields,"
+               Basel: Birkhauser Verlag, 2001.
 
         Examples
         --------
@@ -3089,9 +3105,9 @@ cdef class RandomState:
         """
         logistic(loc=0.0, scale=1.0, size=None)
 
-        Draw samples from a Logistic distribution.
+        Draw samples from a logistic distribution.
 
-        Samples are drawn from a Logistic distribution with specified
+        Samples are drawn from a logistic distribution with specified
         parameters, loc (location or mean, also median), and scale (>0).
 
         Parameters
@@ -3131,14 +3147,14 @@ cdef class RandomState:
 
         References
         ----------
-        .. [1] Reiss, R.-D. and Thomas M. (2001), Statistical Analysis of Extreme
-               Values, from Insurance, Finance, Hydrology and Other Fields,
-               Birkhauser Verlag, Basel, pp 132-133.
+        .. [1] Reiss, R.-D. and Thomas M. (2001), "Statistical Analysis of
+               Extreme Values, from Insurance, Finance, Hydrology and Other
+               Fields," Birkhauser Verlag, Basel, pp 132-133.
         .. [2] Weisstein, Eric W. "Logistic Distribution." From
                MathWorld--A Wolfram Web Resource.
                http://mathworld.wolfram.com/LogisticDistribution.html
         .. [3] Wikipedia, "Logistic-distribution",
-               http://en.wikipedia.org/wiki/Logistic-distribution
+               http://en.wikipedia.org/wiki/Logistic_distribution
 
         Examples
         --------
@@ -3180,7 +3196,7 @@ cdef class RandomState:
         """
         lognormal(mean=0.0, sigma=1.0, size=None)
 
-        Return samples drawn from a log-normal distribution.
+        Draw samples from a log-normal distribution.
 
         Draw samples from a log-normal distribution with specified mean,
         standard deviation, and array shape.  Note that the mean and standard
@@ -3228,12 +3244,12 @@ cdef class RandomState:
 
         References
         ----------
-        Limpert, E., Stahel, W. A., and Abbt, M., "Log-normal Distributions
-        across the Sciences: Keys and Clues," *BioScience*, Vol. 51, No. 5,
-        May, 2001.  http://stat.ethz.ch/~stahel/lognormal/bioscience.pdf
-
-        Reiss, R.D. and Thomas, M., *Statistical Analysis of Extreme Values*,
-        Basel: Birkhauser Verlag, 2001, pp. 31-32.
+        .. [1] Limpert, E., Stahel, W. A., and Abbt, M., "Log-normal
+               Distributions across the Sciences: Keys and Clues,"
+               BioScience, Vol. 51, No. 5, May, 2001.
+               http://stat.ethz.ch/~stahel/lognormal/bioscience.pdf
+        .. [2] Reiss, R.D. and Thomas, M., "Statistical Analysis of Extreme
+               Values," Basel: Birkhauser Verlag, 2001, pp. 31-32.
 
         Examples
         --------
@@ -3257,7 +3273,8 @@ cdef class RandomState:
         >>> plt.show()
 
         Demonstrate that taking the products of random samples from a uniform
-        distribution can be fit well by a log-normal probability density function.
+        distribution can be fit well by a log-normal probability density
+        function.
 
         >>> # Generate a thousand samples: each is the product of 100 random
         >>> # values, drawn from a normal distribution.
@@ -3331,10 +3348,10 @@ cdef class RandomState:
 
         References
         ----------
-        .. [1] Brighton Webs Ltd., Rayleigh Distribution,
-              http://www.brighton-webs.co.uk/distributions/rayleigh.asp
+        .. [1] Brighton Webs Ltd., "Rayleigh Distribution,"
+               http://www.brighton-webs.co.uk/distributions/rayleigh.asp
         .. [2] Wikipedia, "Rayleigh distribution"
-              http://en.wikipedia.org/wiki/Rayleigh_distribution
+               http://en.wikipedia.org/wiki/Rayleigh_distribution
 
         Examples
         --------
@@ -3379,18 +3396,16 @@ cdef class RandomState:
         """
         wald(mean, scale, size=None)
 
-        Draw samples from a Wald, or Inverse Gaussian, distribution.
+        Draw samples from a Wald, or inverse Gaussian, distribution.
 
         As the scale approaches infinity, the distribution becomes more like a
-        Gaussian.
-
-        Some references claim that the Wald is an Inverse Gaussian with mean=1, but
-        this is by no means universal.
+        Gaussian. Some references claim that the Wald is an inverse Gaussian
+        with mean equal to 1, but this is by no means universal.
 
-        The Inverse Gaussian distribution was first studied in relationship to
-        Brownian motion. In 1956 M.C.K. Tweedie used the name Inverse Gaussian
-        because there is an inverse relationship between the time to cover a unit
-        distance and distance covered in unit time.
+        The inverse Gaussian distribution was first studied in relationship to
+        Brownian motion. In 1956 M.C.K. Tweedie used the name inverse Gaussian
+        because there is an inverse relationship between the time to cover a
+        unit distance and distance covered in unit time.
 
         Parameters
         ----------
@@ -3415,20 +3430,20 @@ cdef class RandomState:
         .. math:: P(x;mean,scale) = \\sqrt{\\frac{scale}{2\\pi x^3}}e^
                                     \\frac{-scale(x-mean)^2}{2\\cdotp mean^2x}
 
-        As noted above the Inverse Gaussian distribution first arise from attempts
-        to model Brownian Motion. It is also a competitor to the Weibull for use in
-        reliability modeling and modeling stock returns and interest rate
-        processes.
+        As noted above the inverse Gaussian distribution first arise
+        from attempts to model Brownian motion. It is also a
+        competitor to the Weibull for use in reliability modeling and
+        modeling stock returns and interest rate processes.
 
         References
         ----------
         .. [1] Brighton Webs Ltd., Wald Distribution,
-              http://www.brighton-webs.co.uk/distributions/wald.asp
+               http://www.brighton-webs.co.uk/distributions/wald.asp
         .. [2] Chhikara, Raj S., and Folks, J. Leroy, "The Inverse Gaussian
-              Distribution: Theory : Methodology, and Applications", CRC Press,
-              1988.
+               Distribution: Theory : Methodology, and Applications", CRC Press,
+               1988.
         .. [3] Wikipedia, "Wald distribution"
-              http://en.wikipedia.org/wiki/Wald_distribution
+               http://en.wikipedia.org/wiki/Wald_distribution
 
         Examples
         --------
@@ -3468,9 +3483,10 @@ cdef class RandomState:
 
         Draw samples from the triangular distribution.
 
-        The triangular distribution is a continuous probability distribution with
-        lower limit left, peak at mode, and upper limit right. Unlike the other
-        distributions, these parameters directly define the shape of the pdf.
+        The triangular distribution is a continuous probability
+        distribution with lower limit left, peak at mode, and upper
+        limit right. Unlike the other distributions, these parameters
+        directly define the shape of the pdf.
 
         Parameters
         ----------
@@ -3493,7 +3509,7 @@ cdef class RandomState:
 
         Notes
         -----
-        The probability density function for the Triangular distribution is
+        The probability density function for the triangular distribution is
 
         .. math:: P(x;l, m, r) = \\begin{cases}
                   \\frac{2(x-l)}{(r-l)(m-l)}& \\text{for $l \\leq x \\leq m$},\\\\
@@ -3501,14 +3517,15 @@ cdef class RandomState:
                   0& \\text{otherwise}.
                   \\end{cases}
 
-        The triangular distribution is often used in ill-defined problems where the
-        underlying distribution is not known, but some knowledge of the limits and
-        mode exists. Often it is used in simulations.
+        The triangular distribution is often used in ill-defined
+        problems where the underlying distribution is not known, but
+        some knowledge of the limits and mode exists. Often it is used
+        in simulations.
 
         References
         ----------
         .. [1] Wikipedia, "Triangular distribution"
-              http://en.wikipedia.org/wiki/Triangular_distribution
+               http://en.wikipedia.org/wiki/Triangular_distribution
 
         Examples
         --------
@@ -3533,8 +3550,8 @@ cdef class RandomState:
                 raise ValueError("mode > right")
             if fleft == fright:
                 raise ValueError("left == right")
-            return cont3_array_sc(self.internal_state, rk_triangular, size, fleft,
-                                  fmode, fright, self.lock)
+            return cont3_array_sc(self.internal_state, rk_triangular, size,
+                                  fleft, fmode, fright, self.lock)
 
         PyErr_Clear()
         oleft = <ndarray>PyArray_FROM_OTF(left, NPY_DOUBLE, NPY_ARRAY_ALIGNED)
@@ -3557,7 +3574,7 @@ cdef class RandomState:
 
         Draw samples from a binomial distribution.
 
-        Samples are drawn from a Binomial distribution with specified
+        Samples are drawn from a binomial distribution with specified
         parameters, n trials and p probability of success where
         n an integer >= 0 and p is in the interval [0,1]. (n may be
         input as a float, but it is truncated to an integer in use)
@@ -3585,7 +3602,7 @@ cdef class RandomState:
 
         Notes
         -----
-        The probability density for the Binomial distribution is
+        The probability density for the binomial distribution is
 
         .. math:: P(N) = \\binom{n}{N}p^N(1-p)^{n-N},
 
@@ -3618,7 +3635,7 @@ cdef class RandomState:
         --------
         Draw samples from the distribution:
 
-        >>> n, p = 10, .5 # number of trials, probability of each trial
+        >>> n, p = 10, .5  # number of trials, probability of each trial
         >>> s = np.random.binomial(n, p, 1000)
         # result of flipping a coin 10 times, tested 1000 times.
 
@@ -3629,8 +3646,8 @@ cdef class RandomState:
         Let's do 20,000 trials of the model, and count the number that
         generate zero positive results.
 
-        >>> sum(np.random.binomial(9,0.1,20000)==0)/20000.
-        answer = 0.38885, or 38%.
+        >>> sum(np.random.binomial(9, 0.1, 20000) == 0)/20000.
+        # answer = 0.38885, or 38%.
 
         """
         cdef ndarray on, op
@@ -3668,9 +3685,9 @@ cdef class RandomState:
         """
         negative_binomial(n, p, size=None)
 
-        Draw samples from a negative_binomial distribution.
+        Draw samples from a negative binomial distribution.
 
-        Samples are drawn from a negative_Binomial distribution with specified
+        Samples are drawn from a negative binomial distribution with specified
         parameters, `n` trials and `p` probability of success where `n` is an
         integer > 0 and `p` is in the interval [0, 1].
 
@@ -3692,19 +3709,19 @@ cdef class RandomState:
 
         Notes
         -----
-        The probability density for the Negative Binomial distribution is
+        The probability density for the negative binomial distribution is
 
         .. math:: P(N;n,p) = \\binom{N+n-1}{n-1}p^{n}(1-p)^{N},
 
-        where :math:`n-1` is the number of successes, :math:`p` is the probability
-        of success, and :math:`N+n-1` is the number of trials.
+        where :math:`n-1` is the number of successes, :math:`p` is the
+        probability of success, and :math:`N+n-1` is the number of trials.
+        The negative binomial distribution gives the probability of n-1
+        successes and N failures in N+n-1 trials, and success on the (N+n)th
+        trial.
 
-        The negative binomial distribution gives the probability of n-1 successes
-        and N failures in N+n-1 trials, and success on the (N+n)th trial.
-
-        If one throws a die repeatedly until the third time a "1" appears, then the
-        probability distribution of the number of non-"1"s that appear before the
-        third "1" is a negative binomial distribution.
+        If one throws a die repeatedly until the third time a "1" appears,
+        then the probability distribution of the number of non-"1"s that
+        appear before the third "1" is a negative binomial distribution.
 
         References
         ----------
@@ -3718,11 +3735,11 @@ cdef class RandomState:
         --------
         Draw samples from the distribution:
 
-        A real world example. A company drills wild-cat oil exploration wells, each
-        with an estimated probability of success of 0.1.  What is the probability
-        of having one success for each successive well, that is what is the
-        probability of a single success after drilling 5 wells, after 6 wells,
-        etc.?
+        A real world example. A company drills wild-cat oil
+        exploration wells, each with an estimated probability of
+        success of 0.1.  What is the probability of having one success
+        for each successive well, that is what is the probability of a
+        single success after drilling 5 wells, after 6 wells, etc.?
 
         >>> s = np.random.negative_binomial(1, 0.1, 100000)
         >>> for i in range(1, 11):
@@ -3766,8 +3783,8 @@ cdef class RandomState:
 
         Draw samples from a Poisson distribution.
 
-        The Poisson distribution is the limit of the Binomial
-        distribution for large N.
+        The Poisson distribution is the limit of the binomial distribution
+        for large N.
 
         Parameters
         ----------
@@ -3779,6 +3796,11 @@ cdef class RandomState:
             ``m * n * k`` samples are drawn.  Default is None, in which case a
             single value is returned.
 
+        Returns
+        -------
+        samples : ndarray or scalar
+            The drawn samples, of shape *size*, if it was provided.
+
         Notes
         -----
         The Poisson distribution
@@ -3787,7 +3809,8 @@ cdef class RandomState:
 
         For events with an expected separation :math:`\\lambda` the Poisson
         distribution :math:`f(k; \\lambda)` describes the probability of
-        :math:`k` events occurring within the observed interval :math:`\\lambda`.
+        :math:`k` events occurring within the observed
+        interval :math:`\\lambda`.
 
         Because the output is limited to the range of the C long type, a
         ValueError is raised when `lam` is within 10 sigma of the maximum
@@ -3795,10 +3818,11 @@ cdef class RandomState:
 
         References
         ----------
-        .. [1] Weisstein, Eric W. "Poisson Distribution." From MathWorld--A Wolfram
-               Web Resource. http://mathworld.wolfram.com/PoissonDistribution.html
+        .. [1] Weisstein, Eric W. "Poisson Distribution."
+               From MathWorld--A Wolfram Web Resource.
+               http://mathworld.wolfram.com/PoissonDistribution.html
         .. [2] Wikipedia, "Poisson distribution",
-           http://en.wikipedia.org/wiki/Poisson_distribution
+               http://en.wikipedia.org/wiki/Poisson_distribution
 
         Examples
         --------
@@ -3836,7 +3860,8 @@ cdef class RandomState:
             raise ValueError("lam < 0")
         if np.any(np.greater(olam, self.poisson_lam_max)):
             raise ValueError("lam value too large.")
-        return discd_array(self.internal_state, rk_poisson, size, olam, self.lock)
+        return discd_array(self.internal_state, rk_poisson, size, olam,
+                           self.lock)
 
     def zipf(self, a, size=None):
         """
@@ -3885,8 +3910,9 @@ cdef class RandomState:
 
         References
         ----------
-        Zipf, G. K., *Selected Studies of the Principle of Relative Frequency
-        in Language*, Cambridge, MA: Harvard Univ. Press, 1932.
+        .. [1] Zipf, G. K., "Selected Studies of the Principle of Relative
+               Frequency in Language," Cambridge, MA: Harvard Univ. Press,
+               1932.
 
         Examples
         --------
@@ -3991,7 +4017,8 @@ cdef class RandomState:
             raise ValueError("p < 0.0")
         if np.any(np.greater(op, 1.0)):
             raise ValueError("p > 1.0")
-        return discd_array(self.internal_state, rk_geometric, size, op, self.lock)
+        return discd_array(self.internal_state, rk_geometric, size, op,
+                           self.lock)
 
     def hypergeometric(self, ngood, nbad, nsample, size=None):
         """
@@ -3999,7 +4026,7 @@ cdef class RandomState:
 
         Draw samples from a Hypergeometric distribution.
 
-        Samples are drawn from a Hypergeometric distribution with specified
+        Samples are drawn from a hypergeometric distribution with specified
         parameters, ngood (ways to make a good selection), nbad (ways to make
         a bad selection), and nsample = number of items sampled, which is less
         than or equal to the sum ngood + nbad.
@@ -4041,14 +4068,14 @@ cdef class RandomState:
 
         Consider an urn with black and white marbles in it, ngood of them
         black and nbad are white. If you draw nsample balls without
-        replacement, then the Hypergeometric distribution describes the
+        replacement, then the hypergeometric distribution describes the
         distribution of black balls in the drawn sample.
 
-        Note that this distribution is very similar to the Binomial
+        Note that this distribution is very similar to the binomial
         distribution, except that in this case, samples are drawn without
         replacement, whereas in the Binomial case samples are drawn with
         replacement (or the sample space is infinite). As the sample space
-        becomes large, this distribution approaches the Binomial.
+        becomes large, this distribution approaches the binomial.
 
         References
         ----------
@@ -4058,7 +4085,7 @@ cdef class RandomState:
                MathWorld--A Wolfram Web Resource.
                http://mathworld.wolfram.com/HypergeometricDistribution.html
         .. [3] Wikipedia, "Hypergeometric-distribution",
-               http://en.wikipedia.org/wiki/Hypergeometric-distribution
+               http://en.wikipedia.org/wiki/Hypergeometric_distribution
 
         Examples
         --------
@@ -4101,7 +4128,8 @@ cdef class RandomState:
 
         ongood = <ndarray>PyArray_FROM_OTF(ngood, NPY_LONG, NPY_ARRAY_ALIGNED)
         onbad = <ndarray>PyArray_FROM_OTF(nbad, NPY_LONG, NPY_ARRAY_ALIGNED)
-        onsample = <ndarray>PyArray_FROM_OTF(nsample, NPY_LONG, NPY_ARRAY_ALIGNED)
+        onsample = <ndarray>PyArray_FROM_OTF(nsample, NPY_LONG,
+                                             NPY_ARRAY_ALIGNED)
         if np.any(np.less(ongood, 0)):
             raise ValueError("ngood < 0")
         if np.any(np.less(onbad, 0)):
@@ -4117,10 +4145,10 @@ cdef class RandomState:
         """
         logseries(p, size=None)
 
-        Draw samples from a Logarithmic Series distribution.
+        Draw samples from a logarithmic series distribution.
 
-        Samples are drawn from a Log Series distribution with specified
-        parameter, p (probability, 0 < p < 1).
+        Samples are drawn from a log series distribution with specified
+        shape parameter, 0 < ``p`` < 1.
 
         Parameters
         ----------
@@ -4151,7 +4179,7 @@ cdef class RandomState:
 
         where p = probability.
 
-        The Log Series distribution is frequently used to represent species
+        The log series distribution is frequently used to represent species
         richness and occurrence, first proposed by Fisher, Corbet, and
         Williams in 1943 [2].  It may also be used to model the numbers of
         occupants seen in cars [3].
@@ -4207,7 +4235,8 @@ cdef class RandomState:
             raise ValueError("p <= 0.0")
         if np.any(np.greater_equal(op, 1.0)):
             raise ValueError("p >= 1.0")
-        return discd_array(self.internal_state, rk_logseries, size, op, self.lock)
+        return discd_array(self.internal_state, rk_logseries, size, op,
+                           self.lock)
 
     # Multivariate distributions:
     def multivariate_normal(self, mean, cov, size=None):
@@ -4286,11 +4315,10 @@ cdef class RandomState:
 
         References
         ----------
-        Papoulis, A., *Probability, Random Variables, and Stochastic Processes*,
-        3rd ed., New York: McGraw-Hill, 1991.
-
-        Duda, R. O., Hart, P. E., and Stork, D. G., *Pattern Classification*,
-        2nd ed., New York: Wiley, 2001.
+        .. [1] Papoulis, A., "Probability, Random Variables, and Stochastic
+               Processes," 3rd ed., New York: McGraw-Hill, 1991.
+        .. [2] Duda, R. O., Hart, P. E., and Stork, D. G., "Pattern
+               Classification," 2nd ed., New York: Wiley, 2001.
 
         Examples
         --------
@@ -4370,8 +4398,8 @@ cdef class RandomState:
         possible outcomes.  An example of such an experiment is throwing a dice,
         where the outcome can be 1 through 6.  Each sample drawn from the
         distribution represents `n` such experiments.  Its values,
-        ``X_i = [X_0, X_1, ..., X_p]``, represent the number of times the outcome
-        was ``i``.
+        ``X_i = [X_0, X_1, ..., X_p]``, represent the number of times the
+        outcome was ``i``.
 
         Parameters
         ----------
@@ -4382,10 +4410,19 @@ cdef class RandomState:
             should sum to 1 (however, the last element is always assumed to
             account for the remaining probability, as long as
             ``sum(pvals[:-1]) <= 1)``.
-        size : tuple of ints
-            Given a `size` of ``(M, N, K)``, then ``M*N*K`` samples are drawn,
-            and the output shape becomes ``(M, N, K, p)``, since each sample
-            has shape ``(p,)``.
+        size : int or tuple of ints, optional
+            Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
+            ``m * n * k`` samples are drawn.  Default is None, in which case a
+            single value is returned.
+
+        Returns
+        -------
+        out : ndarray
+            The drawn samples, of shape *size*, if that was provided.  If not,
+            the shape is ``(N,)``.
+
+            In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
+            value drawn from the distribution.
 
         Examples
         --------
@@ -4465,13 +4502,15 @@ cdef class RandomState:
         alpha : array
             Parameter of the distribution (k dimension for sample of
             dimension k).
-        size : array
-            Number of samples to draw.
+        size : int or tuple of ints, optional
+            Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
+            ``m * n * k`` samples are drawn.  Default is None, in which case a
+            single value is returned.
 
         Returns
         -------
         samples : ndarray,
-            The drawn samples, of shape (alpha.ndim, size).
+            The drawn samples, of shape (size, alpha.ndim).
 
         Notes
         -----
@@ -4496,8 +4535,8 @@ cdef class RandomState:
         Taking an example cited in Wikipedia, this distribution can be used if
         one wanted to cut strings (each of initial length 1.0) into K pieces
         with different lengths, where each piece had, on average, a designated
-        average length, but allowing some variation in the relative sizes of the
-        pieces.
+        average length, but allowing some variation in the relative sizes of
+        the pieces.
 
         >>> s = np.random.dirichlet((10, 5, 3), 20).transpose()