Import documentation from doc wiki (part 1)

8 files changed, 82 insertions, 62 deletions

diff --git a/numpy/core/code_generators/docstrings.py b/numpy/core/code_generators/docstrings.py
index 7c5aeae26..5360d3bc2 100644
--- a/numpy/core/code_generators/docstrings.py
+++ b/numpy/core/code_generators/docstrings.py
@@ -11,22 +11,20 @@ def add_newdoc(place, name, doc):
 
 add_newdoc('numpy.core.umath', 'absolute',
     """
-    Calculate the absolute value elementwise.
+    Calculate the absolute value element-wise.
 
     Parameters
     ----------
     x : array_like
-        An array-like sequence of values or a scalar.
+        Input array.
 
     Returns
     -------
-    res : {ndarray, scalar}
+    res : ndarray
         An ndarray containing the absolute value of
         each element in `x`.  For complex input, ``a + ib``, the
         absolute value is :math:`\\sqrt{ a^2 + b^2 }`.
 
-        Returns a scalar for scalar input.
-
     Examples
     --------
     >>> x = np.array([-1.2, 1.2])
@@ -1126,6 +1124,13 @@ add_newdoc('numpy.core.umath', 'greater',
     >>> np.greater([4,2],[2,2])
     array([ True, False], dtype=bool)
 
+    If the inputs are ndarrays, then np.greater is equivalent to '>'.
+
+    >>> a = np.array([4,2])
+    >>> b = np.array([2,2])
+    >>> a > b
+    array([ True, False], dtype=bool)
+
     """)
 
 add_newdoc('numpy.core.umath', 'greater_equal',
@@ -2104,14 +2109,15 @@ add_newdoc('numpy.core.umath', 'sqrt',
     Returns
     -------
     y : ndarray
-        The square-root of each element in `x`.  If any element in `x`
+        An array of the same shape as `x`, containing the square-root of
+        each element in `x`.  If any element in `x`
         is complex, a complex array is returned.  If all of the elements
-        of `x` are real, negative elements will return numpy.nan elements.
+        of `x` are real, negative elements return numpy.nan elements.
 
     See Also
     --------
     numpy.lib.scimath.sqrt
-        A version which will return complex numbers when given negative reals.
+        A version which returns complex numbers when given negative reals.
 
     Notes
     -----
diff --git a/numpy/core/defmatrix.py b/numpy/core/defmatrix.py
index 97602918d..a9f0615fc 100644
--- a/numpy/core/defmatrix.py
+++ b/numpy/core/defmatrix.py
@@ -590,6 +590,11 @@ def bmat(obj, ldict=None, gdict=None):
         Input data.  Variables names in the current scope may
         be referenced, even if `obj` is a string.
 
+    Returns
+    -------
+    out : matrix
+        Returns a matrix object, which is a specialized 2-D array.
+
     See Also
     --------
     matrix
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index f3e9f9b5d..a6f4203be 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -294,7 +294,7 @@ def swapaxes(a, axis1, axis2):
     Returns
     -------
     a_swapped : ndarray
-        If `a` is an ndarray, then a view on `a` is returned, otherwise
+        If `a` is an ndarray, then a view of `a` is returned; otherwise
         a new array is created.
 
     Examples
@@ -1176,11 +1176,9 @@ def product (a, axis=None, dtype=None, out=None):
     """
     Return the product of array elements over a given axis.
 
-    Refer to `numpy.prod` for full documentation.
-
     See Also
     --------
-    prod : equivalent function
+    prod : equivalent function; see for details.
 
     """
     try:
@@ -1390,11 +1388,10 @@ def cumproduct(a, axis=None, dtype=None, out=None):
     """
     Return the cumulative product over the given axis.
 
-    See `cumprod` for full documentation.
 
     See Also
     --------
-    cumprod
+    cumprod : equivalent function; see for details.
 
     """
     try:
@@ -1449,7 +1446,7 @@ def ptp(a, axis=None, out=None):
 
 def amax(a, axis=None, out=None):
     """
-    Return the maximum along a given axis.
+    Return the maximum along an axis.
 
     Parameters
     ----------
@@ -1463,19 +1460,19 @@ def amax(a, axis=None, out=None):
 
     Returns
     -------
-    amax : {ndarray, scalar}
+    amax : ndarray
         A new array or a scalar with the result, or a reference to `out`
         if it was specified.
 
     Examples
     --------
-    >>> x = np.arange(4).reshape((2,2))
-    >>> x
+    >>> a = np.arange(4).reshape((2,2))
+    >>> a
     array([[0, 1],
            [2, 3]])
-    >>> np.amax(x,0)
+    >>> np.amax(a, axis=0)
     array([2, 3])
-    >>> np.amax(x,1)
+    >>> np.amax(a, axis=1)
     array([1, 3])
 
     """
@@ -1488,7 +1485,7 @@ def amax(a, axis=None, out=None):
 
 def amin(a, axis=None, out=None):
     """
-    Return the minimum along a given axis.
+    Return the minimum along an axis.
 
     Parameters
     ----------
@@ -1502,19 +1499,21 @@ def amin(a, axis=None, out=None):
 
     Returns
     -------
-    amin : {ndarray, scalar}
+    amin : ndarray
         A new array or a scalar with the result, or a reference to `out` if it
         was specified.
 
     Examples
     --------
-    >>> x = np.arange(4).reshape((2,2))
-    >>> x
+    >>> a = np.arange(4).reshape((2,2))
+    >>> a
     array([[0, 1],
            [2, 3]])
-    >>> np.amin(x,0)
+    >>> np.amin(a)           # Minimum of the flattened array
+    0
+    >>> np.amin(a, axis=0)         # Minima along the first axis
     array([0, 1])
-    >>> np.amin(x,1)
+    >>> np.amin(a, axis=1)         # Minima along the second axis
     array([0, 2])
 
     """
@@ -1640,7 +1639,7 @@ def cumprod(a, axis=None, dtype=None, out=None):
 
     Parameters
     ----------
-    a : array-like
+    a : array_like
         Input array.
     axis : int, optional
         Axis along which the cumulative product is computed.  By default the
@@ -1658,7 +1657,7 @@ def cumprod(a, axis=None, dtype=None, out=None):
 
     Returns
     -------
-    cumprod : ndarray.
+    cumprod : ndarray
         A new array holding the result is returned unless `out` is
         specified, in which case a reference to out is returned.
 
@@ -1925,21 +1924,21 @@ def mean(a, axis=None, dtype=None, out=None):
     a : array_like
         Array containing numbers whose mean is desired. If `a` is not an
         array, a conversion is attempted.
-    axis : {None, int}, optional
+    axis : int, optional
         Axis along which the means are computed. The default is to compute
         the mean of the flattened array.
-    dtype : {None, dtype}, optional
-        Type to use in computing the mean. For integer inputs the default
-        is float64; for floating point inputs it is the same as the input
+    dtype : dtype, optional
+        Type to use in computing the mean. For integer inputs, the default
+        is float64; for floating point, inputs it is the same as the input
         dtype.
-    out : {None, ndarray}, optional
+    out : ndarray, optional
         Alternative output array in which to place the result. It must have
         the same shape as the expected output but the type will be cast if
         necessary.
 
     Returns
     -------
-    mean : {ndarray, scalar}, see dtype parameter above
+    mean : ndarray, see dtype parameter above
         If `out=None`, returns a new array containing the mean values,
         otherwise a reference to the output array is returned.
 
@@ -2050,27 +2049,27 @@ def var(a, axis=None, dtype=None, out=None, ddof=0):
     Parameters
     ----------
     a : array_like
-        Array containing numbers whose variance is desired. If a is not an
+        Array containing numbers whose variance is desired. If `a` is not an
         array, a conversion is attempted.
     axis : int, optional
         Axis along which the variance is computed. The default is to compute
         the variance of the flattened array.
     dtype : dtype, optional
         Type to use in computing the variance. For arrays of integer type
-        the default is float32, for arrays of float types it is the same as
+        the default is float32; for arrays of float types it is the same as
         the array type.
     out : ndarray, optional
         Alternative output array in which to place the result. It must have
-        the same shape as the expected output but the type will be cast if
+        the same shape as the expected output but the type is cast if
         necessary.
     ddof : positive int,optional
-        Means Delta Degrees of Freedom.  The divisor used in calculation is
+        "Delta Degrees of Freedom": the divisor used in calculation is
         N - ddof.
 
     Returns
     -------
-    variance : {ndarray, scalar}, see dtype parameter above
-        If out=None, returns a new array containing the variance, otherwise
+    variance : ndarray, see dtype parameter above
+        If out=None, returns a new array containing the variance; otherwise
         a reference to the output array is returned.
 
     See Also
@@ -2081,7 +2080,7 @@ def var(a, axis=None, dtype=None, out=None, ddof=0):
     Notes
     -----
     The variance is the average of the squared deviations from the mean,
-    i.e.  var = mean(abs(x - x.mean())**2).  The computed variance is biased,
+    i.e.,  var = mean(abs(x - x.mean())**2).  The computed variance is biased,
     i.e., the mean is computed by dividing by the number of elements, N,
     rather than by N-1. Note that for complex numbers the absolute value is
     taken before squaring, so that the result is always real and nonnegative.
diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
index a6570c0c0..c27a0ea45 100644
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -687,20 +687,18 @@ try:
 except ImportError:
     def alterdot():
         """
-        Change `dot`, `vdot`, and `innerproduct` to use accelerated BLAS
-        functions.
-
-        When numpy is built with an accelerated BLAS like ATLAS, the above
-        functions will be replaced to make use of the faster implementations.
-        The faster implementations only affect float32, float64, complex64, and
-        complex128 arrays. Furthermore, only matrix-matrix, matrix-vector, and
-        vector-vector products are accelerated. Products of arrays with larger
-        dimensionalities will not be accelerated since the BLAS API only
-        includes these.
-
-        Typically, the user will never have to call this function. If numpy was
-        built with an accelerated BLAS, this function will be called when numpy
-        is imported.
+        Change `dot`, `vdot`, and `innerproduct` to use accelerated BLAS functions.
+
+        Typically, as a user of Numpy, you do not explicitly call this function. If
+        Numpy is built with an accelerated BLAS, this function is automatically
+        called when Numpy is imported.
+
+        When Numpy is built with an accelerated BLAS like ATLAS, these functions
+        are replaced to make use of the faster implementations.  The faster
+        implementations only affect float32, float64, complex64, and complex128
+        arrays. Furthermore, the BLAS API only includes matrix-matrix,
+        matrix-vector, and vector-vector products. Products of arrays with larger
+        dimensionalities use the built in functions and are not accelerated.
 
         See Also
         --------
diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index 5ca797864..19037d975 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -1128,6 +1128,17 @@ def interp(x, xp, fp, left=None, right=None):
     >>> np.interp(3.14, xp, fp, right=UNDEF)
     -99.0
 
+    Plot an interpolant to the sine function:
+
+    >>> x = np.linspace(0, 2*np.pi, 10)
+    >>> y = np.sin(x)
+    >>> xvals = np.linspace(0, 2*np.pi, 50)
+    >>> yinterp = np.interp(xvals, x, y)
+    >>> import matplotlib.pyplot as plt
+    >>> plt.plot(x, y, 'o')
+    >>> plt.plot(xvals, yinterp, '-x')
+    >>> plt.show()
+
     """
     if isinstance(x, (float, int, number)):
         return compiled_interp([x], xp, fp, left, right).item()
diff --git a/numpy/lib/polynomial.py b/numpy/lib/polynomial.py
index bce7f0e4e..7e3a02107 100644
--- a/numpy/lib/polynomial.py
+++ b/numpy/lib/polynomial.py
@@ -277,7 +277,7 @@ def polyint(p, m=1, k=None):
 
 def polyder(p, m=1):
     """
-    Return the derivative of order m of a polynomial.
+    Return the derivative of the specified order of a polynomial.
 
     Parameters
     ----------
@@ -295,6 +295,7 @@ def polyder(p, m=1):
     See Also
     --------
     polyint : Anti-derivative of a polynomial.
+    poly1d : Class for one-dimensional polynomials.
 
     Examples
     --------
diff --git a/numpy/lib/twodim_base.py b/numpy/lib/twodim_base.py
index 69eecbd87..cc33923ad 100644
--- a/numpy/lib/twodim_base.py
+++ b/numpy/lib/twodim_base.py
@@ -165,14 +165,14 @@ def eye(N, M=None, k=0, dtype=float):
       Number of columns in the output. If None, defaults to `N`.
     k : int, optional
       Index of the diagonal: 0 refers to the main diagonal, a positive value
-      refers to an upper diagonal and a negative value to a lower diagonal.
+      refers to an upper diagonal, and a negative value to a lower diagonal.
     dtype : dtype, optional
       Data-type of the returned array.
 
     Returns
     -------
     I : ndarray (N,M)
-      An array where all elements are equal to zero, except for the k'th
+      An array where all elements are equal to zero, except for the `k`-th
       diagonal, whose values are equal to one.
 
     See Also
diff --git a/numpy/random/mtrand/mtrand.pyx b/numpy/random/mtrand/mtrand.pyx
index 1dd8b9f05..ede469e12 100644
--- a/numpy/random/mtrand/mtrand.pyx
+++ b/numpy/random/mtrand/mtrand.pyx
@@ -1902,7 +1902,7 @@ cdef class RandomState:
         """
         lognormal(mean=0.0, sigma=1.0, size=None)
 
-        Log-normal distribution.
+        Return samples drawn from a log-normal distribution.
 
         Draw samples from a log-normal distribution with specified mean, standard
         deviation, and shape. Note that the mean and standard deviation are not the
@@ -1938,7 +1938,7 @@ cdef class RandomState:
         where :math:`\\mu` is the mean and :math:`\\sigma` is the standard deviation
         of the normally distributed logarithm of the variable.
 
-        A log normal distribution results if a random variable is the *product* of
+        A log-normal distribution results if a random variable is the *product* of
         a large number of independent, identically-distributed variables in the
         same way that a normal distribution results if the variable is the *sum*
         of a large number of independent, identically-distributed variables
@@ -1947,7 +1947,7 @@ cdef class RandomState:
 
         The log-normal distribution is commonly used to model the lifespan of units
         with fatigue-stress failure modes. Since this includes
-        most mechanical systems, the lognormal distribution has widespread
+        most mechanical systems, the log-normal distribution has widespread
         application.
 
         It is also commonly used to model oil field sizes, species abundance, and
@@ -1986,7 +1986,7 @@ 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 pdf.
+        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.