DOC: merge wiki doc edits.

4 files changed, 60 insertions, 46 deletions

diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index 4ab1679e5..2de5c6193 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -2408,7 +2408,7 @@ def hamming(M):
     -----
     The Hamming window is defined as
 
-    .. math::  w(n) = 0.54 + 0.46cos\\left(\\frac{2\\pi{n}}{M-1}\\right)
+    .. math::  w(n) = 0.54 - 0.46cos\\left(\\frac{2\\pi{n}}{M-1}\\right)
                \\qquad 0 \\leq n \\leq M-1
 
     The Hamming was named for R. W. Hamming, an associate of J. W. Tukey and
@@ -3000,8 +3000,8 @@ def percentile(a, q, axis=None, out=None, overwrite_input=False):
     Given a vector V of length N, the qth percentile of V is the qth ranked
     value in a sorted copy of V.  A weighted average of the two nearest
     neighbors is used if the normalized ranking does not match q exactly.
-    The same as the median if ``q=0.5``, the same as the minimum if ``q=0``
-    and the same as the maximum if ``q=1``.
+    The same as the median if ``q=50``, the same as the minimum if ``q=0``
+    and the same as the maximum if ``q=100``.
 
     Examples
     --------
@@ -3108,7 +3108,7 @@ def trapz(y, x=None, dx=1.0, axis=-1):
 
     Returns
     -------
-    out : float
+    trapz : float
         Definite integral as approximated by trapezoidal rule.
 
     See Also
@@ -3547,7 +3547,7 @@ def append(arr, values, axis=None):
 
     Returns
     -------
-    out : ndarray
+    append : ndarray
         A copy of `arr` with `values` appended to `axis`.  Note that `append`
         does not occur in-place: a new array is allocated and filled.  If
         `axis` is None, `out` is a flattened array.
diff --git a/numpy/lib/npyio.py b/numpy/lib/npyio.py
index c502e2cc5..82bac7d81 100644
--- a/numpy/lib/npyio.py
+++ b/numpy/lib/npyio.py
@@ -274,7 +274,7 @@ class NpzFile(object):
 
 def load(file, mmap_mode=None):
     """
-    Load a pickled, ``.npy``, or ``.npz`` binary file.
+    Load an array(s) or pickled objects from .npy, .npz, or pickled files.
 
     Parameters
     ----------
@@ -283,13 +283,11 @@ def load(file, mmap_mode=None):
         If the filename extension is ``.gz``, the file is first decompressed.
     mmap_mode: {None, 'r+', 'r', 'w+', 'c'}, optional
         If not None, then memory-map the file, using the given mode
-        (see `numpy.memmap`).  The mode has no effect for pickled or
-        zipped files.
-        A memory-mapped array is stored on disk, and not directly loaded
-        into memory.  However, it can be accessed and sliced like any
-        ndarray.  Memory mapping is especially useful for accessing
-        small fragments of large files without reading the entire file
-        into memory.
+        (see `numpy.memmap` for a detailed description of the modes).
+        A memory-mapped array is kept on disk. However, it can be accessed
+        and sliced like any ndarray.  Memory mapping is especially useful for
+        accessing small fragments of large files without reading the entire
+        file into memory.
 
     Returns
     -------
@@ -309,9 +307,9 @@ def load(file, mmap_mode=None):
 
     Notes
     -----
-    - If the file contains pickle data, then whatever is stored in the
-      pickle is returned.
-    - If the file is a ``.npy`` file, then an array is returned.
+    - If the file contains pickle data, then whatever object is stored
+      in the pickle is returned.
+    - If the file is a ``.npy`` file, then a single array is returned.
     - If the file is a ``.npz`` file, then a dictionary-like object is
       returned, containing ``{filename: array}`` key-value pairs, one for
       each file in the archive.
@@ -321,7 +319,7 @@ def load(file, mmap_mode=None):
         with load('foo.npz') as data:
             a = data['a']
 
-      The underlyling file descriptor is always closed when exiting the with block.
+      The underlyling file descriptor is closed when exiting the 'with' block.
 
     Examples
     --------
@@ -334,8 +332,10 @@ def load(file, mmap_mode=None):
 
     Store compressed data to disk, and load it again:
 
-    >>> np.savez('/tmp/123.npz', a=np.array([[1, 2, 3], [4, 5, 6]]), b=np.array([1, 2]))
-    >>> data = np.load('/tmp/123.npy')
+    >>> a=np.array([[1, 2, 3], [4, 5, 6]])
+    >>> b=np.array([1, 2])
+    >>> np.savez('/tmp/123.npz', a=a, b=b)
+    >>> data = np.load('/tmp/123.npz')
     >>> data['a']
     array([[1, 2, 3],
            [4, 5, 6]])
@@ -454,12 +454,12 @@ def savez(file, *args, **kwds):
         Either the file name (string) or an open file (file-like object)
         where the data will be saved. If file is a string, the ``.npz``
         extension will be appended to the file name if it is not already there.
-    *args : Arguments, optional
+    args : Arguments, optional
         Arrays to save to the file. Since it is not possible for Python to
         know the names of the arrays outside `savez`, the arrays will be saved
         with names "arr_0", "arr_1", and so on. These arguments can be any
         expression.
-    **kwds : Keyword arguments, optional
+    kwds : Keyword arguments, optional
         Arrays to save to the file. Arrays will be saved in the file with the
         keyword names.
 
@@ -471,6 +471,8 @@ def savez(file, *args, **kwds):
     --------
     save : Save a single array to a binary file in NumPy format.
     savetxt : Save an array to a file as plain text.
+    numpy.savez_compressed : Save several arrays into a compressed .npz file
+    format
 
     Notes
     -----
@@ -491,7 +493,7 @@ def savez(file, *args, **kwds):
     >>> x = np.arange(10)
     >>> y = np.sin(x)
 
-    Using `savez` with *args, the arrays are saved with default names.
+    Using `savez` with \\*args, the arrays are saved with default names.
 
     >>> np.savez(outfile, x, y)
     >>> outfile.seek(0) # Only needed here to simulate closing & reopening file
@@ -501,7 +503,7 @@ def savez(file, *args, **kwds):
     >>> npzfile['arr_0']
     array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
 
-    Using `savez` with **kwds, the arrays are saved with the keyword names.
+    Using `savez` with \\**kwds, the arrays are saved with the keyword names.
 
     >>> outfile = TemporaryFile()
     >>> np.savez(outfile, x=x, y=y)
@@ -512,10 +514,6 @@ def savez(file, *args, **kwds):
     >>> npzfile['x']
     array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
 
-    See Also
-    --------
-    numpy.savez_compressed : Save several arrays into a compressed .npz file format
-
     """
     _savez(file, args, kwds, False)
 
@@ -1210,8 +1208,8 @@ def genfromtxt(fname, dtype=float, comments='#', delimiter=None,
     autostrip : bool, optional
         Whether to automatically strip white spaces from the variables.
     replace_space : char, optional
-        Character(s) used in replacement of white spaces in the variables names.
-        By default, use a '_'.
+        Character(s) used in replacement of white spaces in the variables
+        names. By default, use a '_'.
     case_sensitive : {True, False, 'upper', 'lower'}, optional
         If True, field names are case sensitive.
         If False or 'upper', field names are converted to upper case.
@@ -1247,6 +1245,11 @@ def genfromtxt(fname, dtype=float, comments='#', delimiter=None,
     * Individual values are not stripped of spaces by default.
       When using a custom converter, make sure the function does remove spaces.
 
+    References
+    ----------
+    .. [1] Numpy User Guide, section `I/O with Numpy
+           <http://docs.scipy.org/doc/numpy/user/basics.io.genfromtxt.html>`_.
+
     Examples
     ---------
     >>> from StringIO import StringIO
@@ -1770,8 +1773,9 @@ def ndfromtxt(fname, **kwargs):
     """
     Load ASCII data stored in a file and return it as a single array.
 
-    Complete description of all the optional input parameters is available in
-    the docstring of the `genfromtxt` function.
+    Parameters
+    ----------
+    fname, kwargs : For a description of input parameters, see `genfromtxt`.
 
     See Also
     --------
@@ -1786,7 +1790,9 @@ def mafromtxt(fname, **kwargs):
     """
     Load ASCII data stored in a text file and return a masked array.
 
-    For a complete description of all the input parameters, see `genfromtxt`.
+    Parameters
+    ----------
+    fname, kwargs : For a description of input parameters, see `genfromtxt`.
 
     See Also
     --------
@@ -1804,8 +1810,9 @@ def recfromtxt(fname, **kwargs):
     If ``usemask=False`` a standard `recarray` is returned,
     if ``usemask=True`` a MaskedRecords array is returned.
 
-    Complete description of all the optional input parameters is available in
-    the docstring of the `genfromtxt` function.
+    Parameters
+    ----------
+    fname, kwargs : For a description of input parameters, see `genfromtxt`.
 
     See Also
     --------
@@ -1836,7 +1843,9 @@ def recfromcsv(fname, **kwargs):
     `recarray`) or a masked record array (if ``usemask=True``,
     see `ma.mrecords.MaskedRecords`).
 
-    For a complete description of all the input parameters, see `genfromtxt`.
+    Parameters
+    ----------
+    fname, kwargs : For a description of input parameters, see `genfromtxt`.
 
     See Also
     --------
diff --git a/numpy/lib/shape_base.py b/numpy/lib/shape_base.py
index 946cf172a..b88596ca4 100644
--- a/numpy/lib/shape_base.py
+++ b/numpy/lib/shape_base.py
@@ -29,7 +29,7 @@ def apply_along_axis(func1d,axis,arr,*args):
 
     Returns
     -------
-    outarr : ndarray
+    apply_along_axis : ndarray
         The output array. The shape of `outarr` is identical to the shape of
         `arr`, except along the `axis` dimension, where the length of `outarr`
         is equal to the size of the return value of `func1d`.  If `func1d`
@@ -142,7 +142,7 @@ def apply_over_axes(func, a, axes):
 
     Returns
     -------
-    val : ndarray
+    apply_over_axis : ndarray
         The output array.  The number of dimensions is the same as `a`,
         but the shape can be different.  This depends on whether `func`
         changes the shape of its output with respect to its input.
diff --git a/numpy/lib/twodim_base.py b/numpy/lib/twodim_base.py
index 6fb348275..58d8250a1 100644
--- a/numpy/lib/twodim_base.py
+++ b/numpy/lib/twodim_base.py
@@ -358,7 +358,7 @@ def tri(N, M=None, k=0, dtype=float):
 
     Returns
     -------
-    T : ndarray of shape (N, M)
+    tri : ndarray of shape (N, M)
         Array with its lower triangle filled with ones and zero elsewhere;
         in other words ``T[i,j] == 1`` for ``i <= j + k``, 0 otherwise.
 
@@ -396,7 +396,7 @@ def tril(m, k=0):
 
     Returns
     -------
-    L : ndarray, shape (M, N)
+    tril : ndarray, shape (M, N)
         Lower triangle of `m`, of same shape and data-type as `m`.
 
     See Also
@@ -790,9 +790,10 @@ def triu_indices(n, k=0):
 
     Returns
     -------
-    inds : tuple of arrays
+    inds : tuple, shape(2) of ndarrays, shape(`n`)
         The indices for the triangle. The returned tuple contains two arrays,
-        each with the indices along one dimension of the array.
+        each with the indices along one dimension of the array.  Can be used
+        to slice a ndarray of shape(`n`, `n`).
 
     See also
     --------
@@ -852,17 +853,21 @@ def triu_indices(n, k=0):
 
 def triu_indices_from(arr, k=0):
     """
-    Return the indices for the upper-triangle of an (n, n) array.
+    Return the indices for the upper-triangle of a (N, N) array.
 
     See `triu_indices` for full details.
 
     Parameters
     ----------
-    arr : array_like
-        The indices will be valid for square arrays whose dimensions are
-        the same as arr.
+    arr : ndarray, shape(N, N)
+        The indices will be valid for square arrays.
     k : int, optional
-      Diagonal offset (see `triu` for details).
+        Diagonal offset (see `triu` for details).
+
+    Returns
+    -------
+    triu_indices_from : tuple, shape(2) of ndarray, shape(N)
+        Indices for the upper-triangle of `arr`.
 
     See Also
     --------