Merge from the doc wiki

11 files changed, 606 insertions, 284 deletions

diff --git a/numpy/lib/arraysetops.py b/numpy/lib/arraysetops.py
index f023f6027..9afb00f29 100644
--- a/numpy/lib/arraysetops.py
+++ b/numpy/lib/arraysetops.py
@@ -52,17 +52,16 @@ def ediff1d(ary, to_end=None, to_begin=None):
         If provided, this number will be taked onto the beginning of the
         returned differences.
 
-    Notes
-    -----
-    When applied to masked arrays, this function drops the mask information
-    if the `to_begin` and/or `to_end` parameters are used
-
-
     Returns
     -------
     ed : array
         The differences. Loosely, this will be (ary[1:] - ary[:-1]).
 
+    Notes
+    -----
+    When applied to masked arrays, this function drops the mask information
+    if the `to_begin` and/or `to_end` parameters are used
+
     """
     ary = np.asanyarray(ary).flat
     ed = ary[1:] - ary[:-1]
@@ -285,11 +284,22 @@ def setmember1d(ar1, ar2):
     mask : ndarray, bool
         The values `ar1[mask]` are in `ar2`.
 
+
     See Also
     --------
     numpy.lib.arraysetops : Module with a number of other functions for
                             performing set operations on arrays.
 
+    Examples
+    --------
+    >>> test = np.arange(5)
+    >>> states = [0, 2]
+    >>> mask = np.setmember1d(test,states)
+    >>> mask
+    array([ True, False,  True, False, False], dtype=bool)
+    >>> test[mask]
+    array([0, 2])
+
     """
     ar1 = np.asarray( ar1 )
     ar2 = np.asarray( ar2 )
diff --git a/numpy/lib/financial.py b/numpy/lib/financial.py
index f53a77631..0cef1c4d2 100644
--- a/numpy/lib/financial.py
+++ b/numpy/lib/financial.py
@@ -190,7 +190,6 @@ def nper(rate, pmt, pv, fv=0, when='end'):
     >>> np.nper(*(np.ogrid[0.06/12:0.071/12:0.01/12, -200:-99:100, 6000:7001:1000]))
     array([[[ 32.58497782,  38.57048452],
             [ 71.51317802,  86.37179563]],
-    <BLANKLINE>
            [[ 33.07413144,  39.26244268],
             [ 74.06368256,  90.22989997]]])
 
diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index b7b1552b0..f76bf2a78 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -242,7 +242,6 @@ def histogram(a, bins=10, range=None, normed=False, weights=None, new=None):
         Return the bin edges ``(length(hist)+1)``.
         With ``new=False``, return the left bin edges (``length(hist)``).
 
-
     See Also
     --------
     histogramdd
@@ -1241,8 +1240,9 @@ def sort_complex(a):
     --------
     >>> np.sort_complex([5, 3, 6, 2, 1])
     array([ 1.+0.j,  2.+0.j,  3.+0.j,  5.+0.j,  6.+0.j])
-    >>> np.sort_complex([5 + 2j, 3 - 1j, 6 - 2j, 2 - 3j, 1 - 5j])
-    array([ 1.-5.j,  2.-3.j,  3.-1.j,  5.+2.j,  6.-2.j])
+
+    >>> np.sort_complex([1 + 2j, 2 - 1j, 3 - 2j, 3 - 3j, 3 + 5j])
+    array([ 1.+2.j,  2.-1.j,  3.-5.j,  3.-3.j,  3.+2.j])
 
     """
     b = array(a,copy=True)
@@ -1259,21 +1259,35 @@ def sort_complex(a):
 
 def trim_zeros(filt, trim='fb'):
     """
-    Trim the leading and trailing zeros from a 1D array.
+    Trim the leading and/or trailing zeros from a 1-D array or sequence.
 
     Parameters
     ----------
-    filt : array_like
+    filt : 1-D array or sequence
         Input array.
-    trim : string, optional
+    trim : str, optional
         A string with 'f' representing trim from front and 'b' to trim from
-        back.
+        back. Default is 'fb', trim zeros from both front and back of the
+        array.
+
+    Returns
+    -------
+    trimmed : 1-D array or sequence
+        The result of trimming the input. The input data type is preserved.
 
     Examples
     --------
-    >>> a = np.array((0, 0, 0, 1, 2, 3, 2, 1, 0))
+    >>> a = np.array((0, 0, 0, 1, 2, 3, 0, 2, 1, 0))
     >>> np.trim_zeros(a)
-    array([1, 2, 3, 2, 1])
+    array([1, 2, 3, 0, 2, 1])
+
+    >>> np.trim_zeros(a, 'b')
+    array([0, 0, 0, 1, 2, 3, 0, 2, 1])
+
+    The input data type is preserved, list/tuple in means list/tuple out.
+
+    >>> np.trim_zeros([0, 1, 2, 0])
+    [1, 2]
 
     """
     first = 0
@@ -1299,7 +1313,7 @@ def unique(x):
 
     Parameters
     ----------
-    x : array_like
+    x : ndarray or sequence
         Input array.
 
     Returns
@@ -1315,6 +1329,9 @@ def unique(x):
     >>> np.unique(a)
     array([1, 2, 3])
 
+    >>> np.unique([True, True, False])
+    array([False,  True], dtype=bool)
+
     """
     try:
         tmp = x.flatten()
@@ -1719,40 +1736,65 @@ def _get_nargs(obj):
 
 class vectorize(object):
     """
-    vectorize(somefunction, otypes=None, doc=None)
+    vectorize(pyfunc, otypes='', doc=None)
 
     Generalized function class.
 
-    Define a vectorized function which takes nested sequence
+    Define a vectorized function which takes a nested sequence
     of objects or numpy arrays as inputs and returns a
-    numpy array as output, evaluating the function over successive
-    tuples of the input arrays like the python map function except it uses
-    the broadcasting rules of numpy.
+    numpy array as output. The vectorized function evaluates `pyfunc` over
+    successive tuples of the input arrays like the python map function,
+    except it uses the broadcasting rules of numpy.
 
-    Data-type of output of vectorized is determined by calling the function
-    with the first element of the input.  This can be avoided by specifying
-    the otypes argument as either a string of typecode characters or a list
-    of data-types specifiers.  There should be one data-type specifier for
-    each output.
+    The data type of the output of `vectorized` is determined by calling
+    the function with the first element of the input.  This can be avoided
+    by specifying the `otypes` argument.
 
     Parameters
     ----------
-    f : callable
-      A Python function or method.
+    pyfunc : callable
+        A python function or method.
+    otypes : str or list of dtypes, optional
+        The output data type. It must be specified as either a string of
+        typecode characters or a list of data type specifiers. There should
+        be one data type specifier for each output.
+    doc : str, optional
+        The docstring for the function. If None, the docstring will be the
+        `pyfunc` one.
 
     Examples
     --------
     >>> def myfunc(a, b):
-    ...    if a > b:
-    ...        return a-b
-    ...    else:
-    ...        return a+b
+    ...     \"\"\"Return a-b if a>b, otherwise return a+b\"\"\"
+    ...     if a > b:
+    ...         return a - b
+    ...     else:
+    ...         return a + b
 
     >>> vfunc = np.vectorize(myfunc)
-
     >>> vfunc([1, 2, 3, 4], 2)
     array([3, 4, 1, 2])
 
+    The docstring is taken from the input function to `vectorize` unless it
+    is specified
+
+    >>> vfunc.__doc__
+    'Return a-b if a>b, otherwise return a+b'
+    >>> vfunc = np.vectorize(myfunc, doc='Vectorized `myfunc`')
+    >>> vfunc.__doc__
+    'Vectorized `myfunc`'
+
+    The output type is determined by evaluating the first element of the input,
+    unless it is specified
+
+    >>> out = vfunc([1, 2, 3, 4], 2)
+    >>> type(out[0])
+    <type 'numpy.int32'>
+    >>> vfunc = np.vectorize(myfunc, otypes=[np.float])
+    >>> out = vfunc([1, 2, 3, 4], 2)
+    >>> type(out[0])
+    <type 'numpy.float64'>
+
     """
     def __init__(self, pyfunc, otypes='', doc=None):
         self.thefunc = pyfunc
@@ -2675,8 +2717,8 @@ def median(a, axis=None, out=None, overwrite_input=False):
     a : array_like
         Input array or object that can be converted to an array.
     axis : {None, int}, optional
-        Axis along which the medians are computed. The default (axis=None) is to
-        compute the median along a flattened version of the array.
+        Axis along which the medians are computed. The default (axis=None)
+        is to compute the median along a flattened version of the array.
     out : ndarray, optional
         Alternative output array in which to place the result. It must
         have the same shape and buffer length as the expected output,
@@ -2840,30 +2882,29 @@ def meshgrid(x,y):
     """
     Return coordinate matrices from two coordinate vectors.
 
-
-
-
     Parameters
     ----------
     x, y : ndarray
-        Two 1D arrays representing the x and y coordinates
+        Two 1-D arrays representing the x and y coordinates of a grid.
 
     Returns
     -------
     X, Y : ndarray
-        For vectors `x`, `y` with lengths Nx=len(`x`) and Ny=len(`y`),
-        return `X`, `Y` where `X` and `Y` are (Ny, Nx) shaped arrays
+        For vectors `x`, `y` with lengths ``Nx=len(x)`` and ``Ny=len(y)``,
+        return `X`, `Y` where `X` and `Y` are ``(Ny, Nx)`` shaped arrays
         with the elements of `x` and y repeated to fill the matrix along
         the first dimension for `x`, the second for `y`.
 
     See Also
     --------
-    numpy.mgrid : Construct a multi-dimensional "meshgrid"
-                               using indexing notation.
+    index_tricks.mgrid : Construct a multi-dimensional "meshgrid"
+                         using indexing notation.
+    index_tricks.ogrid : Construct an open multi-dimensional "meshgrid"
+                         using indexing notation.
 
     Examples
     --------
-    >>> X, Y = numpy.meshgrid([1,2,3], [4,5,6,7])
+    >>> X, Y = np.meshgrid([1,2,3], [4,5,6,7])
     >>> X
     array([[1, 2, 3],
            [1, 2, 3],
@@ -2875,6 +2916,13 @@ def meshgrid(x,y):
            [6, 6, 6],
            [7, 7, 7]])
 
+    `meshgrid` is very useful to evaluate functions on a grid.
+
+    >>> x = np.arange(-5, 5, 0.1)
+    >>> y = np.arange(-5, 5, 0.1)
+    >>> xx, yy = np.meshgrid(x, y)
+    >>> z = np.sin(xx**2+yy**2)/(xx**2+yy**2)
+
     """
     x = asarray(x)
     y = asarray(y)
@@ -2894,20 +2942,27 @@ def delete(arr, obj, axis=None):
     ----------
     arr : array_like
       Input array.
-    obj : slice, integer or an array of integers
+    obj : slice, int or array of ints
       Indicate which sub-arrays to remove.
-    axis : integer, optional
+    axis : int, optional
       The axis along which to delete the subarray defined by `obj`.
       If `axis` is None, `obj` is applied to the flattened array.
 
+    Returns
+    -------
+    out : ndarray
+        A copy of `arr` with the elements specified by `obj` removed. Note
+        that `delete` does not occur in-place. If `axis` is None, `out` is
+        a flattened array.
+
     See Also
     --------
-    insert : Insert values into an array.
-    append : Append values at the end of an array.
+    insert : Insert elements into an array.
+    append : Append elements at the end of an array.
 
     Examples
     --------
-    >>> arr = np.array([[1,2,3,4],[5,6,7,8],[9,10,11,12]])
+    >>> arr = np.array([[1,2,3,4], [5,6,7,8], [9,10,11,12]])
     >>> arr
     array([[ 1,  2,  3,  4],
            [ 5,  6,  7,  8],
@@ -2915,6 +2970,7 @@ def delete(arr, obj, axis=None):
     >>> np.delete(arr, 1, 0)
     array([[ 1,  2,  3,  4],
            [ 9, 10, 11, 12]])
+
     >>> np.delete(arr, np.s_[::2], 1)
     array([[ 2,  4],
            [ 6,  8],
@@ -3012,25 +3068,52 @@ def insert(arr, obj, values, axis=None):
     ----------
     arr : array_like
         Input array.
-    obj : {integer, slice, integer array_like}
+    obj : int, slice, or array of ints
         Insert `values` before `obj` indices.
-    values :
-        Values to insert into `arr`.
+    values : array_like
+        Values to insert into `arr`. If the type of `values` is different
+        from that of `arr`, `values` is converted to the type of `arr`.
     axis : int, optional
-        Axis along which to insert `values`.  If `axis` is None then ravel
-        `arr` first.
+        Axis along which to insert `values`.  If `axis` is None then `arr`
+        is flattened first.
+
+    Returns
+    -------
+    out : ndarray
+        A copy of `arr` with `values` inserted.  Note that `insert`
+        does not occur in-place: a new array is returned. If
+        `axis` is None, `out` is a flattened array.
+
+    See Also
+    --------
+    append : Append elements at the end of an array.
+    delete : Delete elements from an array.
 
     Examples
     --------
-    >>> a = np.array([[1,2,3],
-    ...               [4,5,6],
-    ...               [7,8,9]])
-    >>> np.insert(a, [1,2], [[4],[5]], axis=0)
-    array([[1, 2, 3],
-           [4, 4, 4],
-           [4, 5, 6],
-           [5, 5, 5],
-           [7, 8, 9]])
+    >>> a = np.array([[1, 1], [2, 2], [3, 3]])
+    >>> a
+    array([[1, 1],
+           [2, 2],
+           [3, 3]])
+    >>> np.insert(a, 1, 5)
+    array([1, 5, 1, 2, 2, 3, 3])
+    >>> np.insert(a, 1, 5, axis=1)
+    array([[1, 5, 1],
+           [2, 5, 2],
+           [3, 5, 3]])
+
+    >>> b = a.flatten()
+    >>> b
+    array([1, 1, 2, 2, 3, 3])
+    >>> np.insert(b, [2, 2], [5, 6])
+    array([1, 1, 5, 6, 2, 2, 3, 3])
+
+    >>> np.insert(b, slice(2, 4), [5, 6])
+    array([1, 1, 5, 2, 6, 2, 3, 3])
+
+    >>> np.insert(b, [2, 2], [7.13, False])
+    array([1, 1, 7, 0, 2, 2, 3, 3])
 
     """
     wrap = None
@@ -3121,13 +3204,21 @@ def append(arr, values, axis=None):
     -------
     out : 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.
+        does not occur in-place: a new array is allocated and filled.  If
+        `axis` is None, `out` is a flattened array.
+
+    See Also
+    --------
+    insert : Insert elements into an array.
+    delete : Delete elements from an array.
 
     Examples
     --------
     >>> np.append([1, 2, 3], [[4, 5, 6], [7, 8, 9]])
     array([1, 2, 3, 4, 5, 6, 7, 8, 9])
 
+    When `axis` is specified, `values` must have the correct shape.
+
     >>> np.append([[1, 2, 3], [4, 5, 6]], [[7, 8, 9]], axis=0)
     array([[1, 2, 3],
            [4, 5, 6],
diff --git a/numpy/lib/index_tricks.py b/numpy/lib/index_tricks.py
index fcd3909af..b8add9ed7 100644
--- a/numpy/lib/index_tricks.py
+++ b/numpy/lib/index_tricks.py
@@ -34,7 +34,7 @@ def unravel_index(x,dims):
 
     Examples
     --------
-    >>> arr = np.ones((5,4))
+    >>> arr = np.arange(20).reshape(5,4)
     >>> arr
     array([[ 0,  1,  2,  3],
            [ 4,  5,  6,  7],
@@ -130,7 +130,6 @@ class nd_grid(object):
             [2, 2, 2, 2, 2],
             [3, 3, 3, 3, 3],
             [4, 4, 4, 4, 4]],
-    <BLANKLINE>
            [[0, 1, 2, 3, 4],
             [0, 1, 2, 3, 4],
             [0, 1, 2, 3, 4],
@@ -396,11 +395,20 @@ class ndenumerate(object):
 
 
 class ndindex(object):
-    """Pass in a sequence of integers corresponding
-    to the number of dimensions in the counter.  This iterator
-    will then return an N-dimensional counter.
+    """
+    An N-dimensional iterator object to index arrays.
+
+    Given the shape of an array, an `ndindex` instance iterates over
+    the N-dimensional index of the array. At each iteration, the index of the
+    last dimension is incremented by one.
 
-    Example:
+    Parameters
+    ----------
+    `*args` : integers
+      The size of each dimension in the counter.
+
+    Examples
+    --------
     >>> for index in np.ndindex(3,2,1):
     ...     print index
     (0, 0, 0)
diff --git a/numpy/lib/io.py b/numpy/lib/io.py
index a4bd7f9ee..84790ac42 100644
--- a/numpy/lib/io.py
+++ b/numpy/lib/io.py
@@ -212,6 +212,11 @@ def save(file, arr):
     x : array_like
         Array data.
 
+    See Also
+    --------
+    savez : Save several arrays into an .npz compressed archive
+    savetxt : Save an array to a file as plain text
+
     Examples
     --------
     >>> from tempfile import TemporaryFile
@@ -237,21 +242,36 @@ def save(file, arr):
 
 def savez(file, *args, **kwds):
     """
-    Save several arrays into an .npz file format which is a zipped-archive
-    of arrays
+    Save several arrays into a single, compressed file with extension ".npz"
 
-    If keyword arguments are given, then filenames are taken from the keywords.
-    If arguments are passed in with no keywords, then stored file names are
-    arr_0, arr_1, etc.
+    If keyword arguments are given, the names for variables assigned to the
+    keywords are the keyword names (not the variable names in the caller).
+    If arguments are passed in with no keywords, the corresponding variable
+    names are arr_0, arr_1, etc.
 
     Parameters
     ----------
-    file : string
-        File name of .npz file.
+    file : Either the filename (string) or an open file (file-like object)
+        If file is a string, it names the output file.  ".npz" will be appended
+        if it is not already there.
     args : Arguments
-        Function arguments.
+        Any function arguments other than the file name are variables to save.
+        Since it is not possible for Python to know their names outside the
+        savez function, they will be saved with names "arr_0", "arr_1", and so
+        on.  These arguments can be any expression.
     kwds : Keyword arguments
-        Keywords.
+        All keyword=value pairs cause the value to be saved with the name of
+        the keyword.
+
+    See Also
+    --------
+    save : Save a single array to a binary file in NumPy format
+    savetxt : Save an array to a file as plain text
+
+    Notes
+    -----
+    The .npz file format is a zipped archive of files named after the variables
+    they contain.  Each file contains one variable in .npy format.
 
     """
 
@@ -510,6 +530,11 @@ def savetxt(fname, X, fmt='%.18e',delimiter=' '):
     delimiter : str
         Character separating columns.
 
+    See Also
+    --------
+    save : Save an array to a binary file in NumPy format
+    savez : Save several arrays into an .npz compressed archive
+
     Notes
     -----
     Further explanation of the `fmt` parameter
diff --git a/numpy/lib/polynomial.py b/numpy/lib/polynomial.py
index 10fd6dd6c..5c3d146f8 100644
--- a/numpy/lib/polynomial.py
+++ b/numpy/lib/polynomial.py
@@ -621,7 +621,7 @@ def polysub(a1, a2):
 
     Examples
     --------
-    .. math:: (2 x^2 + 10x - 2) - (3 x^2 + 10x -4) = (-x^2 + 2)
+    .. math:: (2 x^2 + 10 x - 2) - (3 x^2 + 10 x -4) = (-x^2 + 2)
 
     >>> np.polysub([2, 10, -2], [3, 10, -4])
     array([-1,  0,  2])
diff --git a/numpy/lib/shape_base.py b/numpy/lib/shape_base.py
index a890a8a2b..19dd54f7a 100644
--- a/numpy/lib/shape_base.py
+++ b/numpy/lib/shape_base.py
@@ -10,30 +10,30 @@ from numpy.core.fromnumeric import product, reshape
 
 def apply_along_axis(func1d,axis,arr,*args):
     """
-    Apply function to 1-D slices along the given axis.
+    Apply a function to 1-D slices along the given axis.
 
-    Execute `func1d(a[i],*args)` where `func1d` takes 1-D arrays, `a` is
-    the input array, and `i` is an integer that varies in order to apply the
-    function along the given axis for each 1-D subarray in `a`.
+    Execute `func1d(a, *args)` where `func1d` operates on 1-D arrays and `a`
+    is a 1-D slice of `arr` along `axis`.
 
     Parameters
     ----------
     func1d : function
-        This function should be able to take 1-D arrays. It is applied to 1-D
-        slices of `a` along the specified axis.
+        This function should accept 1-D arrays. It is applied to 1-D
+        slices of `arr` along the specified axis.
     axis : integer
-        Axis along which `func1d` is applied.
-    a : ndarray
+        Axis along which `arr` is sliced.
+    arr : ndarray
         Input array.
     args : any
         Additional arguments to `func1d`.
 
     Returns
     -------
-    out : ndarray
-        The output array. The shape of `out` is identical to the shape of `a`,
-        except along the `axis` dimension, whose length is equal to the size
-        of the return value of `func1d`.
+    outarr : 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`
+        returns a scalar `outarr` will have one fewer dimensions than `arr`.
 
     See Also
     --------
@@ -50,6 +50,18 @@ def apply_along_axis(func1d,axis,arr,*args):
     >>> np.apply_along_axis(my_func, 1, b)
     array([2., 5., 8.])
 
+    For a function that doesn't return a scalar, the number of dimensions in
+    `outarr` is the same as `arr`.
+
+    >>> def new_func(a):
+    ...     \"\"\"Divide elements of a by 2.\"\"\"
+    ...     return a * 0.5
+    >>> b = np.array([[1,2,3], [4,5,6], [7,8,9]])
+    >>> np.apply_along_axis(new_func, 0, b)
+    array([[ 0.5,  1. ,  1.5],
+           [ 2. ,  2.5,  3. ],
+           [ 3.5,  4. ,  4.5]])
+
     """
     arr = asarray(arr)
     nd = arr.ndim
@@ -148,7 +160,6 @@ def apply_over_axes(func, a, axes):
     array([[[ 0,  1,  2,  3],
             [ 4,  5,  6,  7],
             [ 8,  9, 10, 11]],
-    <BLANKLINE>
            [[12, 13, 14, 15],
             [16, 17, 18, 19],
             [20, 21, 22, 23]]])
@@ -310,13 +321,13 @@ def atleast_2d(*arys):
 
     Examples
     --------
-    >>> numpy.atleast_2d(3.0)
+    >>> np.atleast_2d(3.0)
     array([[ 3.]])
 
-    >>> x = numpy.arange(3.0)
-    >>> numpy.atleast_2d(x)
+    >>> x = np.arange(3.0)
+    >>> np.atleast_2d(x)
     array([[ 0.,  1.,  2.]])
-    >>> numpy.atleast_2d(x).base is x
+    >>> np.atleast_2d(x).base is x
     True
 
     >>> np.atleast_2d(1, [1, 2], [[1, 2]])
@@ -347,38 +358,37 @@ def atleast_3d(*arys):
     res1, res2, ... : ndarray
         An array, or tuple of arrays, each with ``a.ndim >= 3``.
         Copies are avoided where possible, and views with three or more
-        dimensions are returned.  For example, a one-dimensional array of
-        shape ``N`` becomes a view of shape ``(1, N, 1)``.  An ``(M, N)``
-        array becomes a view of shape ``(N, M, 1)``.
+        dimensions are returned.  For example, a 1-D array of shape ``N``
+        becomes a view of shape ``(1, N, 1)``.  A 2-D array of shape ``(M, N)``
+        becomes a view of shape ``(M, N, 1)``.
 
     See Also
     --------
-    numpy.atleast_1d, numpy.atleast_2d
+    atleast_1d, atleast_2d
 
     Examples
     --------
-    >>> numpy.atleast_3d(3.0)
+    >>> np.atleast_3d(3.0)
     array([[[ 3.]]])
 
-    >>> x = numpy.arange(3.0)
-    >>> numpy.atleast_3d(x).shape
+    >>> x = np.arange(3.0)
+    >>> np.atleast_3d(x).shape
     (1, 3, 1)
 
-    >>> x = numpy.arange(12.0).reshape(4,3)
-    >>> numpy.atleast_3d(x).shape
+    >>> x = np.arange(12.0).reshape(4,3)
+    >>> np.atleast_3d(x).shape
     (4, 3, 1)
-    >>> numpy.atleast_3d(x).base is x
+    >>> np.atleast_3d(x).base is x
     True
 
-    >>> for arr in np.atleast_3d(1, [1, 2], [[1, 2]]): print arr, "\\n"
+    >>> for arr in np.atleast_3d([1, 2], [[1, 2]], [[[1, 2]]]):
+    ...     print arr, arr.shape
     ...
-    [[[1]]]
-
     [[[1]
-      [2]]]
-
+      [2]]] (1, 2, 1)
     [[[1]
-      [2]]]
+      [2]]] (1, 2, 1)
+    [[[1 2]]] (1, 1, 2)
 
     """
     res = []
@@ -401,27 +411,33 @@ def atleast_3d(*arys):
 
 def vstack(tup):
     """
-    Stack arrays vertically.
+    Stack arrays in sequence vertically (row wise).
 
-    `vstack` can be used to rebuild arrays divided by `vsplit`.
+    Take a sequence of arrays and stack them vertically to make a single
+    array. Rebuild arrays divided by `vsplit`.
 
     Parameters
     ----------
-    tup : sequence of arrays
-        Tuple containing arrays to be stacked.  The arrays must have the same
+    tup : sequence of ndarrays
+        Tuple containing arrays to be stacked. The arrays must have the same
         shape along all but the first axis.
 
+    Returns
+    -------
+    stacked : ndarray
+        The array formed by stacking the given arrays.
+
     See Also
     --------
-    array_split : Split an array into a list of multiple sub-arrays of
-                  near-equal size.
-    split : Split array into a list of multiple sub-arrays of equal size.
-    vsplit : Split array into a list of multiple sub-arrays vertically.
-    dsplit : Split array into a list of multiple sub-arrays along the 3rd axis
-             (depth).
-    concatenate : Join arrays together.
     hstack : Stack arrays in sequence horizontally (column wise).
     dstack : Stack arrays in sequence depth wise (along third dimension).
+    concatenate : Join a sequence of arrays together.
+    vsplit : Split array into a list of multiple sub-arrays vertically.
+
+
+    Notes
+    -----
+    Equivalent to ``np.concatenate(tup, axis=0)``
 
     Examples
     --------
@@ -430,6 +446,7 @@ def vstack(tup):
     >>> np.vstack((a,b))
     array([[1, 2, 3],
            [2, 3, 4]])
+
     >>> a = np.array([[1], [2], [3]])
     >>> b = np.array([[2], [3], [4]])
     >>> np.vstack((a,b))
@@ -445,7 +462,7 @@ def vstack(tup):
 
 def hstack(tup):
     """
-    Stack arrays in sequence horizontally (column wise)
+    Stack arrays in sequence horizontally (column wise).
 
     Take a sequence of arrays and stack them horizontally to make
     a single array. Rebuild arrays divided by ``hsplit``.
@@ -462,9 +479,9 @@ def hstack(tup):
 
     See Also
     --------
-    vstack : Stack along first axis.
-    dstack : Stack along third axis.
-    concatenate : Join arrays.
+    vstack : Stack arrays in sequence vertically (row wise).
+    dstack : Stack arrays in sequence depth wise (along third axis).
+    concatenate : Join a sequence of arrays together.
     hsplit : Split array along second axis.
 
     Notes
@@ -491,11 +508,11 @@ row_stack = vstack
 
 def column_stack(tup):
     """
-    Stack 1-D arrays as columns into a 2-D array
+    Stack 1-D arrays as columns into a 2-D array.
 
     Take a sequence of 1-D arrays and stack them as columns
     to make a single 2-D array. 2-D arrays are stacked as-is,
-    just like with hstack.  1-D arrays are turned into 2-D columns
+    just like with `hstack`.  1-D arrays are turned into 2-D columns
     first.
 
     Parameters
@@ -503,6 +520,19 @@ def column_stack(tup):
     tup : sequence of 1-D or 2-D arrays.
         Arrays to stack. All of them must have the same first dimension.
 
+    Returns
+    -------
+    stacked : 2-D array
+        The array formed by stacking the given arrays.
+
+    See Also
+    --------
+    hstack, vstack, concatenate
+
+    Notes
+    -----
+    This function is equivalent to ``np.vstack(tup).T``.
+
     Examples
     --------
     >>> a = np.array((1,2,3))
@@ -523,7 +553,7 @@ def column_stack(tup):
 
 def dstack(tup):
     """
-    Stack arrays in sequence depth wise (along third axis)
+    Stack arrays in sequence depth wise (along third axis).
 
     Takes a sequence of arrays and stack them along the third axis
     to make a single array. Rebuilds arrays divided by ``dsplit``.
@@ -560,13 +590,12 @@ def dstack(tup):
     array([[[1, 2],
             [2, 3],
             [3, 4]]])
+
     >>> a = np.array([[1],[2],[3]])
     >>> b = np.array([[2],[3],[4]])
     >>> np.dstack((a,b))
     array([[[1, 2]],
-    <BLANKLINE>
            [[2, 3]],
-    <BLANKLINE>
            [[3, 4]]])
 
     """
@@ -584,13 +613,14 @@ def array_split(ary,indices_or_sections,axis = 0):
     """
     Split an array into multiple sub-arrays of equal or near-equal size.
 
-    Please refer to the `numpy.split` documentation.  The only difference
-    between these functions is that `array_split` allows `indices_or_sections`
-    to be an integer that does *not* equally divide the axis.
+    Please refer to the ``split`` documentation.  The only difference
+    between these functions is that ``array_split`` allows
+    `indices_or_sections` to be an integer that does *not* equally
+    divide the axis.
 
     See Also
     --------
-    numpy.split : Split array into multiple sub-arrays.
+    split : Split array into multiple sub-arrays of equal size.
 
     Examples
     --------
@@ -638,12 +668,12 @@ def split(ary,indices_or_sections,axis=0):
     ----------
     ary : ndarray
         Array to be divided into sub-arrays.
-    indices_or_sections: integer or 1D array
+    indices_or_sections : int or 1-D array
         If `indices_or_sections` is an integer, N, the array will be divided
         into N equal arrays along `axis`.  If such a split is not possible,
         an error is raised.
 
-        If `indices_or_sections` is a 1D array of sorted integers, the entries
+        If `indices_or_sections` is a 1-D array of sorted integers, the entries
         indicate where along `axis` the array is split.  For example,
         ``[2, 3]`` would, for ``axis = 0``, result in
 
@@ -653,12 +683,12 @@ def split(ary,indices_or_sections,axis=0):
 
         If an index exceeds the dimension of the array along `axis`,
         an empty sub-array is returned correspondingly.
-    axis : integer, optional
-        The axis along which to split.  Default is 0.
+    axis : int, optional
+        The axis along which to split, default is 0.
 
     Returns
     -------
-    sub-arrays : list
+    sub-arrays : list of ndarrays
         A list of sub-arrays.
 
     Raises
@@ -688,7 +718,6 @@ def split(ary,indices_or_sections,axis=0):
 
     >>> x = np.arange(8.0)
     >>> np.split(x, [3, 5, 6, 10])
-    <BLANKLINE>
     [array([ 0.,  1.,  2.]),
      array([ 3.,  4.]),
      array([ 5.]),
@@ -707,20 +736,25 @@ def split(ary,indices_or_sections,axis=0):
 
 def hsplit(ary,indices_or_sections):
     """
-    Split array into multiple sub-arrays horizontally.
+    Split an array into multiple sub-arrays horizontally (column-wise).
 
-    Please refer to the `numpy.split` documentation.  `hsplit` is
-    equivalent to `numpy.split` with ``axis = 1``.
+    Please refer to the ``split`` documentation.  ``hsplit`` is equivalent
+    to ``split`` with `axis=1`, the array is always split along the second
+    axis regardless of the array dimension.
 
     See Also
     --------
-    split : Split array into multiple sub-arrays.
+    split : Split an array into multiple sub-arrays of equal size.
 
     Examples
     --------
     >>> x = np.arange(16.0).reshape(4, 4)
+    >>> x
+    array([[  0.,   1.,   2.,   3.],
+           [  4.,   5.,   6.,   7.],
+           [  8.,   9.,  10.,  11.],
+           [ 12.,  13.,  14.,  15.]])
     >>> np.hsplit(x, 2)
-    <BLANKLINE>
     [array([[  0.,   1.],
            [  4.,   5.],
            [  8.,   9.],
@@ -729,9 +763,7 @@ def hsplit(ary,indices_or_sections):
            [  6.,   7.],
            [ 10.,  11.],
            [ 14.,  15.]])]
-
-    >>> np.hsplit(x, array([3, 6]))
-    <BLANKLINE>
+    >>> np.hsplit(x, np.array([3, 6]))
     [array([[  0.,   1.,   2.],
            [  4.,   5.,   6.],
            [  8.,   9.,  10.],
@@ -742,6 +774,20 @@ def hsplit(ary,indices_or_sections):
            [ 15.]]),
      array([], dtype=float64)]
 
+    With a higher dimensional array the split is still along the second axis.
+
+    >>> x = np.arange(8.0).reshape(2, 2, 2)
+    >>> x
+    array([[[ 0.,  1.],
+            [ 2.,  3.]],
+           [[ 4.,  5.],
+            [ 6.,  7.]]])
+    >>> np.hsplit(x, 2)
+    [array([[[ 0.,  1.]],
+           [[ 4.,  5.]]]),
+     array([[[ 2.,  3.]],
+           [[ 6.,  7.]]])]
+
     """
     if len(_nx.shape(ary)) == 0:
         raise ValueError, 'hsplit only works on arrays of 1 or more dimensions'
@@ -752,14 +798,49 @@ def hsplit(ary,indices_or_sections):
 
 def vsplit(ary,indices_or_sections):
     """
-    Split array into multiple sub-arrays vertically.
+    Split an array into multiple sub-arrays vertically (row-wise).
 
-    Please refer to the `numpy.split` documentation.
+    Please refer to the ``split`` documentation.  ``vsplit`` is equivalent
+    to ``split`` with `axis=0` (default), the array is always split along the
+    first axis regardless of the array dimension.
 
     See Also
     --------
-    numpy.split : The default behaviour of this function implements
-                  `vsplit`.
+    split : Split an array into multiple sub-arrays of equal size.
+
+    Examples
+    --------
+    >>> x = np.arange(16.0).reshape(4, 4)
+    >>> x
+    array([[  0.,   1.,   2.,   3.],
+           [  4.,   5.,   6.,   7.],
+           [  8.,   9.,  10.,  11.],
+           [ 12.,  13.,  14.,  15.]])
+    >>> np.vsplit(x, 2)
+    [array([[ 0.,  1.,  2.,  3.],
+           [ 4.,  5.,  6.,  7.]]),
+     array([[  8.,   9.,  10.,  11.],
+           [ 12.,  13.,  14.,  15.]])]
+    >>> np.vsplit(x, np.array([3, 6]))
+    [array([[  0.,   1.,   2.,   3.],
+           [  4.,   5.,   6.,   7.],
+           [  8.,   9.,  10.,  11.]]),
+     array([[ 12.,  13.,  14.,  15.]]),
+     array([], dtype=float64)]
+
+    With a higher dimensional array the split is still along the first axis.
+
+    >>> x = np.arange(8.0).reshape(2, 2, 2)
+    >>> x
+    array([[[ 0.,  1.],
+            [ 2.,  3.]],
+           [[ 4.,  5.],
+            [ 6.,  7.]]])
+    >>> np.vsplit(x, 2)
+    [array([[[ 0.,  1.],
+            [ 2.,  3.]]]),
+     array([[[ 4.,  5.],
+            [ 6.,  7.]]])]
 
     """
     if len(_nx.shape(ary)) < 2:
@@ -770,73 +851,38 @@ def dsplit(ary,indices_or_sections):
     """
     Split array into multiple sub-arrays along the 3rd axis (depth).
 
-    Parameters
-    ----------
-    ary : ndarray
-        An array, with at least 3 dimensions, to be divided into sub-arrays
-        depth-wise, or along the third axis.
-    indices_or_sections: integer or 1D array
-        If `indices_or_sections` is an integer, N, the array will be divided
-        into N equal arrays along `axis`. If an equal split is not possible,
-        a ValueError is raised.
-
-        if `indices_or_sections` is a 1D array of sorted integers representing
-        indices along `axis`, the array will be divided such that each index
-        marks the start of each sub-array. If an index exceeds the dimension of
-        the array along `axis`, and empty sub-array is returned for that index.
-    axis : integer, optional
-      the axis along which to split.  Default is 0.
-
-    Returns
-    -------
-    sub-arrays : list
-        A list of sub-arrays.
+    Please refer to the ``split`` documentation.  ``dsplit`` is equivalent
+    to ``split`` with `axis=2`, the array is always split along the third
+    axis provided the array dimension is greater than or equal to 3.
 
     See Also
     --------
-    array_split : Split an array into a list of multiple sub-arrays
-                  of near-equal size.
-    split : Split array into a list of multiple sub-arrays of equal size.
-    hsplit : Split array into a list of multiple sub-arrays horizontally
-    vsplit : Split array into a list of multiple sub-arrays vertically
-    concatenate : Join arrays together.
-    hstack : Stack arrays in sequence horizontally (column wise)
-    vstack : Stack arrays in sequence vertically (row wise)
-    dstack : Stack arrays in sequence depth wise (along third dimension)
-
-    Notes
-    -----
-    `dsplit` requires that sub-arrays are of equal shape, whereas
-    `array_split` allows for sub-arrays to have nearly-equal shape.
-    Equivalent to `split` with `axis` = 2.
+    split : Split an array into multiple sub-arrays of equal size.
 
     Examples
     --------
     >>> x = np.arange(16.0).reshape(2, 2, 4)
+    >>> x
+    array([[[  0.,   1.,   2.,   3.],
+            [  4.,   5.,   6.,   7.]],
+           [[  8.,   9.,  10.,  11.],
+            [ 12.,  13.,  14.,  15.]]])
     >>> np.dsplit(x, 2)
-    <BLANKLINE>
     [array([[[  0.,   1.],
             [  4.,   5.]],
-    <BLANKLINE>
            [[  8.,   9.],
             [ 12.,  13.]]]),
      array([[[  2.,   3.],
             [  6.,   7.]],
-    <BLANKLINE>
            [[ 10.,  11.],
             [ 14.,  15.]]])]
-    <BLANKLINE>
-    >>> x = np.arange(16.0).reshape(2, 2, 4)
-    >>> np.dsplit(x, array([3, 6]))
-    <BLANKLINE>
+    >>> np.dsplit(x, np.array([3, 6]))
     [array([[[  0.,   1.,   2.],
             [  4.,   5.,   6.]],
-    <BLANKLINE>
            [[  8.,   9.,  10.],
             [ 12.,  13.,  14.]]]),
      array([[[  3.],
             [  7.]],
-    <BLANKLINE>
            [[ 11.],
             [ 15.]]]),
      array([], dtype=float64)]
diff --git a/numpy/lib/twodim_base.py b/numpy/lib/twodim_base.py
index e796a065a..f0abf3122 100644
--- a/numpy/lib/twodim_base.py
+++ b/numpy/lib/twodim_base.py
@@ -10,7 +10,7 @@ from numpy.core.numeric import asanyarray, equal, subtract, arange, \
 
 def fliplr(m):
     """
-    Left-right flip.
+    Flip array in the left/right direction.
 
     Flip the entries in each row in the left/right direction.
     Columns are preserved, but appear in a different order than before.
@@ -33,7 +33,7 @@ def fliplr(m):
 
     Notes
     -----
-    Equivalent to A[::-1,...]. Does not require the array to be
+    Equivalent to A[:,::-1]. Does not require the array to be
     two-dimensional.
 
     Examples
@@ -60,7 +60,7 @@ def fliplr(m):
 
 def flipud(m):
     """
-    Up-down flip.
+    Flip array in the up/down direction.
 
     Flip the entries in each column in the up/down direction.
     Rows are preserved, but appear in a different order than before.
@@ -76,6 +76,11 @@ def flipud(m):
         A view of `m` with the rows reversed.  Since a view is
         returned, this operation is :math:`\\mathcal O(1)`.
 
+    See Also
+    --------
+    fliplr : Flip array in the left/right direction.
+    rot90 : Rotate array counterclockwise.
+
     Notes
     -----
     Equivalent to ``A[::-1,...]``.
@@ -203,11 +208,22 @@ def diag(v, k=0):
     Parameters
     ----------
     v : array_like
-        If `v` is a 2-dimensional array, return a copy of
-        its `k`-th diagonal. If `v` is a 1-dimensional array,
-        return a 2-dimensional array with `v` on the `k`-th diagonal.
+        If `v` is a 2-D array, return a copy of its `k`-th diagonal.
+        If `v` is a 1-D array, return a 2-D array with `v` on the `k`-th
+        diagonal.
     k : int, optional
-        Diagonal in question.  The defaults is 0.
+        Diagonal in question. The default is 0.
+
+    Returns
+    -------
+    out : ndarray
+        The extracted diagonal or constructed diagonal array.
+
+    See Also
+    --------
+    diagonal : Return specified diagonals.
+    diagflat : Create a 2-D array with the flattened input as a diagonal.
+    trace : Sum along diagonals.
 
     Examples
     --------
@@ -255,7 +271,7 @@ def diag(v, k=0):
 
 def diagflat(v,k=0):
     """
-    Create a 2-dimensional array with the flattened input as a diagonal.
+    Create a two-dimensional array with the flattened input as a diagonal.
 
     Parameters
     ----------
@@ -265,9 +281,20 @@ def diagflat(v,k=0):
     k : int, optional
         Diagonal to set.  The default is 0.
 
+    Returns
+    -------
+    out : ndarray
+        The 2-D output array.
+
+    See Also
+    --------
+    diag : Matlab workalike for 1-D and 2-D arrays.
+    diagonal : Return specified diagonals.
+    trace : Sum along diagonals.
+
     Examples
     --------
-    >>> np.diagflat([[1,2],[3,4]])
+    >>> np.diagflat([[1,2], [3,4]])
     array([[1, 0, 0, 0],
            [0, 2, 0, 0],
            [0, 0, 3, 0],
diff --git a/numpy/lib/type_check.py b/numpy/lib/type_check.py
index 6f37326cc..113cec682 100644
--- a/numpy/lib/type_check.py
+++ b/numpy/lib/type_check.py
@@ -43,20 +43,20 @@ def mintypecode(typechars,typeset='GDFgdf',default='d'):
 
 def asfarray(a, dtype=_nx.float_):
     """
-    Return an array converted to float type.
+    Return an array converted to a float type.
 
     Parameters
     ----------
     a : array_like
-        Input array.
-    dtype : string or dtype object, optional
-        Float type code to coerce input array `a`.  If one of the 'int' dtype,
-        it is replaced with float64.
+        The input array.
+    dtype : str or dtype object, optional
+        Float type code to coerce input array `a`.  If `dtype` is one of the
+        'int' dtypes, it is replaced with float64.
 
     Returns
     -------
-    out : ndarray, float
-        Input `a` as a float ndarray.
+    out : ndarray
+        The input `a` as a float ndarray.
 
     Examples
     --------
@@ -126,9 +126,10 @@ def imag(val):
 
 def iscomplex(x):
     """
-    Return a bool array, True if element is complex (non-zero imaginary part).
+    Returns a bool array, where True if input element is complex.
 
-    For scalars, return a boolean.
+    What is tested is whether the input has a non-zero imaginary part, not if
+    the input type is complex.
 
     Parameters
     ----------
@@ -140,11 +141,16 @@ def iscomplex(x):
     out : ndarray, bool
         Output array.
 
+    See Also
+    --------
+    isreal: Returns a bool array, where True if input element is real.
+    iscomplexobj: Return True if x is a complex type or an array of complex
+                  numbers.
+
     Examples
     --------
-    >>> x = np.array([1,2,3.j])
-    >>> np.iscomplex(x)
-    array([False, False,  True], dtype=bool)
+    >>> np.iscomplex([1+1j, 1+0j, 4.5, 3, 2, 2j])
+    array([ True, False, False, False, False,  True], dtype=bool)
 
     """
     ax = asanyarray(x)
@@ -155,9 +161,10 @@ def iscomplex(x):
 
 def isreal(x):
     """
-    Returns a bool array where True if the corresponding input element is real.
+    Returns a bool array, where True if input element is real.
 
-    True if complex part is zero.
+    If the input value has a complex type but with complex part zero, the
+    return value is True.
 
     Parameters
     ----------
@@ -169,6 +176,12 @@ def isreal(x):
     out : ndarray, bool
         Boolean array of same shape as `x`.
 
+    See Also
+    --------
+    iscomplex: Return a bool array, where True if input element is complex
+               (non-zero imaginary part).
+    isrealobj: Return True if x is not a complex type.
+
     Examples
     --------
     >>> np.isreal([1+1j, 1+0j, 4.5, 3, 2, 2j])
@@ -178,16 +191,70 @@ def isreal(x):
     return imag(x) == 0
 
 def iscomplexobj(x):
-    """Return True if x is a complex type or an array of complex numbers.
+    """
+    Return True if x is a complex type or an array of complex numbers.
+
+    The type of the input is checked, not the value. So even if the input
+    has an imaginary part equal to zero, `iscomplexobj` evaluates to True
+    if the data type is complex.
+
+    Parameters
+    ----------
+    x : any
+        The input can be of any type and shape.
+
+    Returns
+    -------
+    y : bool
+        The return value, True if `x` is of a complex type.
+
+    See Also
+    --------
+    isrealobj, iscomplex
+
+    Examples
+    --------
+    >>> np.iscomplexobj(1)
+    False
+    >>> np.iscomplexobj(1+0j)
+    True
+    np.iscomplexobj([3, 1+0j, True])
+    True
 
-    Unlike iscomplex(x), complex(3.0) is considered a complex object.
     """
     return issubclass( asarray(x).dtype.type, _nx.complexfloating)
 
 def isrealobj(x):
-    """Return True if x is not a complex type.
+    """
+    Return True if x is a not complex type or an array of complex numbers.
+
+    The type of the input is checked, not the value. So even if the input
+    has an imaginary part equal to zero, `isrealobj` evaluates to False
+    if the data type is complex.
+
+    Parameters
+    ----------
+    x : any
+        The input can be of any type and shape.
+
+    Returns
+    -------
+    y : bool
+        The return value, False if `x` is of a complex type.
+
+    See Also
+    --------
+    iscomplexobj, isreal
+
+    Examples
+    --------
+    >>> np.isrealobj(1)
+    True
+    >>> np.isrealobj(1+0j)
+    False
+    >>> np.isrealobj([3, 1+0j, True])
+    False
 
-    Unlike isreal(x), complex(3.0) is considered a complex object.
     """
     return not issubclass( asarray(x).dtype.type, _nx.complexfloating)
 
@@ -200,7 +267,11 @@ def _getmaxmin(t):
 
 def nan_to_num(x):
     """
-    Replace nan with zero and inf with large numbers.
+    Replace nan with zero and inf with finite numbers.
+
+    Returns an array or scalar replacing Not a Number (NaN) with zero,
+    (positive) infinity with a very large number and negative infinity
+    with a very small (or negative) number.
 
     Parameters
     ----------
@@ -209,10 +280,26 @@ def nan_to_num(x):
 
     Returns
     -------
-    out : ndarray
-        Array with the same shape and dtype as `x`.  Nan is replaced
-        by zero, and inf (-inf) is replaced by the largest (smallest)
-        floating point value that fits in the output dtype.
+    out : ndarray, float
+        Array with the same shape as `x` and dtype of the element in `x`  with
+        the greatest precision. NaN is replaced by zero, and infinity
+        (-infinity) is replaced by the largest (smallest or most negative)
+        floating point value that fits in the output dtype. All finite numbers
+        are upcast to the output dtype (default float64).
+
+    See Also
+    --------
+    isinf : Shows which elements are negative or negative infinity.
+    isneginf : Shows which elements are negative infinity.
+    isposinf : Shows which elements are positive infinity.
+    isnan : Shows which elements are Not a Number (NaN).
+    isfinite : Shows which elements are finite (not NaN, not infinity)
+
+    Notes
+    -----
+    Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic
+    (IEEE 754). This means that Not a Number is not equivalent to infinity.
+
 
     Examples
     --------
@@ -263,8 +350,9 @@ def real_if_close(a,tol=100):
     ----------
     a : array_like
         Input array.
-    tol : scalar
-        Tolerance for the complex part of the elements in the array.
+    tol : float
+        Tolerance in machine epsilons for the complex part of the elements
+        in the array.
 
     Returns
     -------
@@ -285,12 +373,12 @@ def real_if_close(a,tol=100):
 
     Examples
     --------
-    >>> np.finfo(np.float).eps      # DOCTEST +skip
+    >>> np.finfo(np.float).eps
     2.2204460492503131e-16
 
-    >>> np.real_if_close([2.1 + 4e-14j], tol = 1000)
+    >>> np.real_if_close([2.1 + 4e-14j], tol=1000)
     array([ 2.1])
-    >>> np.real_if_close([2.1 + 4e-13j], tol = 1000)
+    >>> np.real_if_close([2.1 + 4e-13j], tol=1000)
     array([ 2.1 +4.00000000e-13j])
 
     """
@@ -313,17 +401,17 @@ def asscalar(a):
     Parameters
     ----------
     a : ndarray
-        Input array.
+        Input array of size 1.
 
     Returns
     -------
     out : scalar
-        Scalar of size 1 array.
+        Scalar representation of `a`. The input data type is preserved.
 
     Examples
     --------
     >>> np.asscalar(np.array([24]))
-    >>> 24
+    24
 
     """
     return a.item()
diff --git a/numpy/lib/ufunclike.py b/numpy/lib/ufunclike.py
index 8ea7c6662..5dbc3f225 100644
--- a/numpy/lib/ufunclike.py
+++ b/numpy/lib/ufunclike.py
@@ -27,7 +27,7 @@ def fix(x, y=None):
 
     See Also
     --------
-    floor : Round downwards
+    trunc, floor, ceil
     around : Round to given number of decimals
 
     Examples
@@ -50,48 +50,40 @@ def fix(x, y=None):
 
 def isposinf(x, y=None):
     """
-    Shows which elements of the input are positive infinity.
-
-    Returns a numpy array resulting from an element-wise test for positive
-    infinity.
+    Test element-wise for positive infinity, return result as bool array.
 
     Parameters
     ----------
     x : array_like
-      The input array.
-    y : array_like
-      A boolean array with the same shape as `x` to store the result.
+        The input array.
+    y : array_like, optional
+        A boolean array with the same shape as `x` to store the result.
 
     Returns
     -------
     y : ndarray
-      A numpy boolean array with the same dimensions as the input.
-      If second argument is not supplied then a numpy boolean array is returned
-      with values True where the corresponding element of the input is positive
-      infinity and values False where the element of the input is not positive
-      infinity.
+        A boolean array with the same dimensions as the input.
+        If second argument is not supplied then a boolean array is returned
+        with values True where the corresponding element of the input is
+        positive infinity and values False where the element of the input is
+        not positive infinity.
 
-      If second argument is supplied then an numpy integer array is returned
-      with values 1 where the corresponding element of the input is positive
-      positive infinity.
+        If a second argument is supplied the result is stored there. If the
+        type of that array is a numeric type the result is represented as zeros
+        and ones, if the type is boolean then as False and True.
+        The return value `y` is then a reference to that array.
 
     See Also
     --------
-    isinf : Shows which elements are negative or positive infinity.
-    isneginf : Shows which elements are negative infinity.
-    isnan : Shows which elements are Not a Number (NaN).
-    isfinite: Shows which elements are not: Not a number, positive and
-             negative infinity
+    isinf, isneginf, isfinite, isnan
 
     Notes
     -----
     Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic
-    (IEEE 754). This means that Not a Number is not equivalent to infinity.
-    Also that positive infinity is not equivalent to negative infinity. But
-    infinity is equivalent to positive infinity.
+    (IEEE 754).
 
-    Errors result if second argument is also supplied with scalar input or
-    if first and second arguments have different shapes.
+    Errors result if the second argument is also supplied when `x` is a
+    scalar input, or if first and second arguments have different shapes.
 
     Examples
     --------
@@ -103,9 +95,10 @@ def isposinf(x, y=None):
     array(False, dtype=bool)
     >>> np.isposinf([-np.inf, 0., np.inf])
     array([False, False,  True], dtype=bool)
-    >>> x=np.array([-np.inf, 0., np.inf])
-    >>> y=np.array([2,2,2])
-    >>> np.isposinf(x,y)
+
+    >>> x = np.array([-np.inf, 0., np.inf])
+    >>> y = np.array([2, 2, 2])
+    >>> np.isposinf(x, y)
     array([1, 0, 0])
     >>> y
     array([1, 0, 0])
@@ -119,29 +112,60 @@ def isposinf(x, y=None):
 
 def isneginf(x, y=None):
     """
-    Return True where x is -infinity, and False otherwise.
+    Test element-wise for negative infinity, return result as bool array.
 
     Parameters
     ----------
     x : array_like
-      The input array.
-    y : array_like
-      A boolean array with the same shape as `x` to store the result.
+        The input array.
+    y : array_like, optional
+        A boolean array with the same shape and type as `x` to store the
+        result.
 
     Returns
     -------
     y : ndarray
-      A boolean array where y[i] = True only if x[i] = -Inf.
+        A boolean array with the same dimensions as the input.
+        If second argument is not supplied then a numpy boolean array is
+        returned with values True where the corresponding element of the
+        input is negative infinity and values False where the element of
+        the input is not negative infinity.
+
+        If a second argument is supplied the result is stored there. If the
+        type of that array is a numeric type the result is represented as
+        zeros and ones, if the type is boolean then as False and True. The
+        return value `y` is then a reference to that array.
 
     See Also
     --------
-    isposinf, isfinite
+    isinf, isposinf, isnan, isfinite
+
+    Notes
+    -----
+    Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic
+    (IEEE 754).
+
+    Errors result if the second argument is also supplied when x is a scalar
+    input, or if first and second arguments have different shapes.
 
     Examples
     --------
+    >>> np.isneginf(np.NINF)
+    array(True, dtype=bool)
+    >>> np.isneginf(np.inf)
+    array(False, dtype=bool)
+    >>> np.isneginf(np.PINF)
+    array(False, dtype=bool)
     >>> np.isneginf([-np.inf, 0., np.inf])
     array([ True, False, False], dtype=bool)
 
+    >>> x = np.array([-np.inf, 0., np.inf])
+    >>> y = np.array([2, 2, 2])
+    >>> np.isneginf(x, y)
+    array([1, 0, 0])
+    >>> y
+    array([1, 0, 0])
+
     """
     if y is None:
         x = nx.asarray(x)
diff --git a/numpy/lib/utils.py b/numpy/lib/utils.py
index 9717a7a8f..3de0579df 100644
--- a/numpy/lib/utils.py
+++ b/numpy/lib/utils.py
@@ -149,15 +149,21 @@ get_numpy_include = deprecate(get_include, 'get_numpy_include', 'get_include')
 #--------------------------------------------
 
 def byte_bounds(a):
-    """(low, high) are pointers to the end-points of an array
+    """
+    Returns pointers to the end-points of an array.
 
-    low is the first byte
-    high is just *past* the last byte
+    Parameters
+    ----------
+    a : ndarray
+        Input array. It must conform to the Python-side of the array interface.
 
-    If the array is not single-segment, then it may not actually
-    use every byte between these bounds.
+    Returns
+    -------
+    (low, high) : tuple of 2 integers
+        The first integer is the first byte of the array, the second integer is
+        just past the last byte of the array.  If `a` is not contiguous it
+        would not use every byte between the (`low`, `high`) values.
 
-    The array provided must conform to the Python-side of the array interface
     """
     ai = a.__array_interface__
     a_data = ai['data'][0]
@@ -228,10 +234,8 @@ def who(vardict=None):
     >>> np.whos(d)
     Name            Shape            Bytes            Type
     ===========================================================
-    <BLANKLINE>
     y               3                24               float64
     x               2                16               float64
-    <BLANKLINE>
     Upper bound on total bytes  =       40
 
     """