Merge from doc wiki

10 files changed, 844 insertions, 273 deletions

diff --git a/numpy/lib/arraysetops.py b/numpy/lib/arraysetops.py
index c5e7822f2..b1a730efa 100644
--- a/numpy/lib/arraysetops.py
+++ b/numpy/lib/arraysetops.py
@@ -46,23 +46,45 @@ def ediff1d(ary, to_end=None, to_begin=None):
     ----------
     ary : array
         This array will be flattened before the difference is taken.
-    to_end : number, optional
-        If provided, this number will be tacked onto the end of the returned
+    to_end : array_like, optional
+        If provided, this number will be appended to the end of the returned
         differences.
-    to_begin : number, optional
-        If provided, this number will be taked onto the beginning of the
+    to_begin : array_like, optional
+        If provided, this array will be appended to the beginning of the
         returned differences.
 
     Returns
     -------
     ed : array
-        The differences. Loosely, this will be (ary[1:] - ary[:-1]).
+        The differences. Loosely, this will be ``ary[1:] - ary[:-1]``.
+
+    See Also
+    --------
+    diff, gradient
 
     Notes
     -----
     When applied to masked arrays, this function drops the mask information
     if the `to_begin` and/or `to_end` parameters are used
 
+    Examples
+    --------
+    >>> x = np.array([1, 2, 4, 7, 0])
+    >>> np.ediff1d(x)
+    array([ 1,  2,  3, -7])
+
+    >>> np.ediff1d(x, to_begin=-99, to_end=np.array([88, 99]))
+    array([-99,   1,   2,   3,  -7,  88,  99])
+
+    The returned array is always 1D.
+
+    >>> y = np.array([[1, 2, 4], [1, 6, 24]])
+    >>> y
+    array([[ 1,  2,  4],
+           [ 1,  6, 24]])
+    >>> np.ediff1d(y)
+    array([ 1,  2, -3,  5, 18])
+
     """
     ary = np.asanyarray(ary).flat
     ed = ary[1:] - ary[:-1]
@@ -168,28 +190,41 @@ def unique1d(ar1, return_index=False, return_inverse=False):
 
 def intersect1d(ar1, ar2):
     """
-    Intersection returning repeated or unique elements common to both arrays.
+    Find elements that are common to two arrays.
+
+    For speed, it is assumed the two input arrays do not have any
+    repeated elements. To find the intersection of two arrays that
+    have repeated elements, use `intersect1d_nu`.
 
     Parameters
     ----------
     ar1,ar2 : array_like
-        Input arrays.
+        Input arrays. These must be 1D and must not have repeated elements.
 
     Returns
     -------
     out : ndarray, shape(N,)
-        Sorted 1D array of common elements with repeating elements.
+        Sorted array of common elements.
 
     See Also
     --------
-    intersect1d_nu : Returns only unique common elements.
+    intersect1d_nu : Find the intersection for input arrays with
+                     repeated elements.
     numpy.lib.arraysetops : Module with a number of other functions for
                             performing set operations on arrays.
 
     Examples
     --------
-    >>> np.intersect1d([1,3,3],[3,1,1])
-    array([1, 1, 3, 3])
+    >>> np.intersect1d([1, 2, 3], [2, 3, 4])
+    array([2, 3])
+    >>> np.intersect1d(['a','b','c'], ['b','c','d'])
+    array(['b', 'c'],
+          dtype='|S1')
+
+    This function fails if the input arrays have repeated elements.
+
+    >>> np.intersect1d([1, 1, 2, 3, 3, 4], [1, 4])
+    array([1, 1, 3, 4])
 
     """
     aux = np.concatenate((ar1,ar2))
@@ -198,7 +233,11 @@ def intersect1d(ar1, ar2):
 
 def intersect1d_nu(ar1, ar2):
     """
-    Intersection returning unique elements common to both arrays.
+    Find elements common to two arrays.
+
+    Returns an array of unique elements that represents the intersection
+    of the two input arrays.  Unlike `intersect1d`, the input arrays can
+    have repeated elements.
 
     Parameters
     ----------
@@ -208,17 +247,18 @@ def intersect1d_nu(ar1, ar2):
     Returns
     -------
     out : ndarray, shape(N,)
-        Sorted 1D array of common and unique elements.
+        Sorted 1D array of common, unique elements.
 
     See Also
     --------
-    intersect1d : Returns repeated or unique common elements.
+    intersect1d : Faster version of `intersect1d_nu` for 1D input arrays
+                  without repeated elements.
     numpy.lib.arraysetops : Module with a number of other functions for
                             performing set operations on arrays.
 
     Examples
     --------
-    >>> np.intersect1d_nu([1,3,3],[3,1,1])
+    >>> np.intersect1d_nu([1, 3 ,3], [3, 3, 1, 1])
     array([1, 3])
 
     """
@@ -265,43 +305,49 @@ def setxor1d(ar1, ar2):
 
 def setmember1d(ar1, ar2):
     """
-    Return a boolean array set True where first element is in second array.
+    Test whether elements of one array are also present in a second array.
 
-    Boolean array is the shape of `ar1` containing True where the elements
-    of `ar1` are in `ar2` and False otherwise.
-
-    Use unique1d() to generate arrays with only unique elements to use as
-    inputs to this function.
+    Returns a boolean array the same length as `ar1` that is True where an
+    element of `ar1` is also in `ar2` and False otherwise. The input arrays
+    must not contain any repeated elements. If they do, unique arrays can
+    be created using `unique1d()` to use as inputs to this function.
 
     Parameters
     ----------
     ar1 : array_like
-        Input array.
+        Input array. It must not have any repeated elements
     ar2 : array_like
-        Input array.
+        Input array. Again, it must not have any repeated elements.
 
     Returns
     -------
     mask : ndarray, bool
         The values `ar1[mask]` are in `ar2`.
 
-
     See Also
     --------
     setmember1d_nu : Works for arrays with non-unique elements.
     numpy.lib.arraysetops : Module with a number of other functions for
                             performing set operations on arrays.
+    unique1d : Find unique elements in an array.
 
     Examples
     --------
-    >>> test = np.arange(5)
+    >>> test = [0, 1, 2, 3, 4, 5]
     >>> states = [0, 2]
-    >>> mask = np.setmember1d(test,states)
+    >>> mask = np.setmember1d(test, states)
     >>> mask
     array([ True, False,  True, False, False], dtype=bool)
     >>> test[mask]
     array([0, 2])
 
+    This function fails if there are repeated elements in the input arrays:
+
+    >>> test = [0, 1, 1, 2, 3, 3]
+    >>> states = [0, 2]
+    >>> np.setmember1d(test,states)
+    array([ True,  True, False,  True,  True, False], dtype=bool)   # Wrong!
+
     """
     # We need this to be a stable sort, so always use 'mergesort' here. The
     # values from the first array should always come before the values from the
diff --git a/numpy/lib/financial.py b/numpy/lib/financial.py
index 0cef1c4d2..0b9372515 100644
--- a/numpy/lib/financial.py
+++ b/numpy/lib/financial.py
@@ -28,6 +28,18 @@ def fv(rate, nper, pmt, pv, when='end'):
     """
     Compute the future value.
 
+    Given:
+     * a present value, `pv`
+     * an interest `rate` compounded once per period, of which
+       there are
+     * `nper` total
+     * a (fixed) payment, `pmt`, paid either
+     * at the beginning (`when` = {'begin', 1}) or the end
+       (`when` = {'end', 0}) of each period
+
+    Return:
+       the value at the end of the `nper` periods
+
     Parameters
     ----------
     rate : scalar or array_like of shape(M, )
@@ -61,6 +73,17 @@ def fv(rate, nper, pmt, pv, when='end'):
 
      fv + pv + pmt * nper == 0
 
+    References
+    ----------
+    .. [WRW] Wheeler, D. A., E. Rathke, and R. Weir (Eds.) (2009, May).
+       Open Document Format for Office Applications (OpenDocument)v1.2,
+       Part 2: Recalculated Formula (OpenFormula) Format - Annotated Version,
+       Pre-Draft 12. Organization for the Advancement of Structured Information
+       Standards (OASIS). Billerica, MA, USA. [ODT Document].
+       Available:
+       http://www.oasis-open.org/committees/documents.php?wg_abbrev=office-formula
+       OpenDocument-formula-20090508.odt
+
     Examples
     --------
     What is the future value after 10 years of saving $100 now, with
@@ -94,6 +117,19 @@ def pmt(rate, nper, pv, fv=0, when='end'):
     """
     Compute the payment against loan principal plus interest.
 
+    Given:
+     * a present value, `pv` (e.g., an amount borrowed)
+     * a future value, `fv` (e.g., 0)
+     * an interest `rate` compounded once per period, of which
+       there are
+     * `nper` total
+     * and (optional) specification of whether payment is made
+       at the beginning (`when` = {'begin', 1}) or the end
+       (`when` = {'end', 0}) of each period
+
+    Return:
+       the (fixed) periodic payment.
+
     Parameters
     ----------
     rate : array_like
@@ -102,8 +138,8 @@ def pmt(rate, nper, pv, fv=0, when='end'):
         Number of compounding periods
     pv : array_like
         Present value
-    fv : array_like
-        Future value
+    fv : array_like (optional)
+        Future value (default = 0)
     when : {{'begin', 1}, {'end', 0}}, {string, int}
         When payments are due ('begin' (1) or 'end' (0))
 
@@ -117,7 +153,7 @@ def pmt(rate, nper, pv, fv=0, when='end'):
 
     Notes
     -----
-    The payment ``pmt`` is computed by solving the equation::
+    The payment is computed by solving the equation::
 
      fv +
      pv*(1 + rate)**nper +
@@ -127,16 +163,37 @@ def pmt(rate, nper, pv, fv=0, when='end'):
 
       fv + pv + pmt * nper == 0
 
+    for ``pmt``.
+
+    Note that computing a monthly mortgage payment is only
+    one use for this function.  For example, pmt returns the
+    periodic deposit one must make to achieve a specified
+    future balance given an initial deposit, a fixed,
+    periodically compounded interest rate, and the total
+    number of periods.
+
+    References
+    ----------
+    .. [WRW] Wheeler, D. A., E. Rathke, and R. Weir (Eds.) (2009, May).
+       Open Document Format for Office Applications (OpenDocument)v1.2,
+       Part 2: Recalculated Formula (OpenFormula) Format - Annotated Version,
+       Pre-Draft 12. Organization for the Advancement of Structured Information
+       Standards (OASIS). Billerica, MA, USA. [ODT Document].
+       Available:
+       http://www.oasis-open.org/committees/documents.php?wg_abbrev=office-formula
+       OpenDocument-formula-20090508.odt
+
     Examples
     --------
-    What would the monthly payment need to be to pay off a $200,000 loan in 15
+    What is the monthly payment needed to pay off a $200,000 loan in 15
     years at an annual interest rate of 7.5%?
 
     >>> np.pmt(0.075/12, 12*15, 200000)
     -1854.0247200054619
 
-    In order to pay-off (i.e. have a future-value of 0) the $200,000 obtained
-    today, a monthly payment of $1,854.02 would be required.
+    In order to pay-off (i.e., have a future-value of 0) the $200,000 obtained
+    today, a monthly payment of $1,854.02 would be required.  Note that this
+    example illustrates usage of `fv` having a default value of 0.
 
     """
     when = _convert_when(when)
@@ -282,6 +339,18 @@ def pv(rate, nper, pmt, fv=0.0, when='end'):
     """
     Compute the present value.
 
+    Given:
+     * a future value, `fv`
+     * an interest `rate` compounded once per period, of which
+       there are
+     * `nper` total
+     * a (fixed) payment, `pmt`, paid either
+     * at the beginning (`when` = {'begin', 1}) or the end
+       (`when` = {'end', 0}) of each period
+
+    Return:
+       the value now
+
     Parameters
     ----------
     rate : array_like
@@ -302,7 +371,7 @@ def pv(rate, nper, pmt, fv=0.0, when='end'):
 
     Notes
     -----
-    The present value ``pv`` is computed by solving the equation::
+    The present value is computed by solving the equation::
 
      fv +
      pv*(1 + rate)**nper +
@@ -312,6 +381,45 @@ def pv(rate, nper, pmt, fv=0.0, when='end'):
 
      fv + pv + pmt * nper = 0
 
+    for `pv`, which is then returned.
+
+    References
+    ----------
+    .. [WRW] Wheeler, D. A., E. Rathke, and R. Weir (Eds.) (2009, May).
+       Open Document Format for Office Applications (OpenDocument)v1.2,
+       Part 2: Recalculated Formula (OpenFormula) Format - Annotated Version,
+       Pre-Draft 12. Organization for the Advancement of Structured Information
+       Standards (OASIS). Billerica, MA, USA. [ODT Document].
+       Available:
+       http://www.oasis-open.org/committees/documents.php?wg_abbrev=office-formula
+       OpenDocument-formula-20090508.odt
+
+    Examples
+    --------
+    What is the present value (e.g., the initial investment)
+    of an investment that needs to total $15692.93
+    after 10 years of saving $100 every month?  Assume the
+    interest rate is 5% (annually) compounded monthly.
+
+    >>> np.pv(0.05/12, 10*12, -100, 15692.93)
+    -100.00067131625819
+
+    By convention, the negative sign represents cash flow out
+    (i.e., money not available today).  Thus, to end up with
+    $15,692.93 in 10 years saving $100 a month at 5% annual
+    interest, one's initial deposit should also be $100.
+
+    If any input is array_like, ``pv`` returns an array of equal shape.
+    Let's compare different interest rates in the example above:
+
+    >>> a = np.array((0.05, 0.04, 0.03))/12
+    >>> np.pv(a, 10*12, -100, 15692.93)
+    array([ -100.00067132,  -649.26771385, -1273.78633713])
+
+    So, to end up with the same $15692.93 under the same $100 per month
+    "savings plan," for annual interest rates of 4% and 3%, one would
+    need initial investments of $649.27 and $1273.79, respectively.
+
     """
     when = _convert_when(when)
     rate, nper, pmt, fv, when = map(np.asarray, [rate, nper, pmt, fv, when])
@@ -391,24 +499,54 @@ def irr(values):
     """
     Return the Internal Rate of Return (IRR).
 
-    This is the rate of return that gives a net present value of 0.0.
+    This is the "average" periodically compounded rate of return
+    that gives a net present value of 0.0; for a more complete explanation,
+    see Notes below.
 
     Parameters
     ----------
     values : array_like, shape(N,)
-        Input cash flows per time period.  At least the first value would be
-        negative to represent the investment in the project.
+        Input cash flows per time period.  By convention, net "deposits"
+        are negative and net "withdrawals" are positive.  Thus, for example,
+        at least the first element of `values`, which represents the initial
+        investment, will typically be negative.
 
     Returns
     -------
     out : float
         Internal Rate of Return for periodic input values.
 
+    Notes
+    -----
+    The IRR is perhaps best understood through an example (illustrated
+    using np.irr in the Examples section below).  Suppose one invests
+    100 units and then makes the following withdrawals at regular
+    (fixed) intervals: 39, 59, 55, 20.  Assuming the ending value is 0,
+    one's 100 unit investment yields 173 units; however, due to the
+    combination of compounding and the periodic withdrawals, the
+    "average" rate of return is neither simply 0.73/4 nor (1.73)^0.25-1.
+    Rather, it is the solution (for :math:`r`) of the equation:
+
+    .. math:: -100 + \\frac{39}{1+r} + \\frac{59}{(1+r)^2}
+     + \\frac{55}{(1+r)^3} + \\frac{20}{(1+r)^4} = 0
+
+    In general, for `values` :math:`= [v_0, v_1, ... v_M]`,
+    irr is the solution of the equation: [G]_
+
+    .. math:: \\sum_{t=0}^M{\\frac{v_t}{(1+irr)^{t}}} = 0
+
+    References
+    ----------
+    .. [G] L. J. Gitman, "Principles of Managerial Finance, Brief," 3rd ed.,
+       Addison-Wesley, 2003, pg. 348.
+
     Examples
     --------
     >>> np.irr([-100, 39, 59, 55, 20])
     0.2809484211599611
 
+    (Compare with the Example given for numpy.lib.financial.npv)
+
     """
     res = np.roots(values[::-1])
     # Find the root(s) between 0 and 1
@@ -430,8 +568,14 @@ def npv(rate, values):
     rate : scalar
         The discount rate.
     values : array_like, shape(M, )
-        The values of the time series of cash flows.  Must be the same
-        increment as the `rate`.
+        The values of the time series of cash flows.  The (fixed) time
+        interval between cash flow "events" must be the same as that
+        for which `rate` is given (i.e., if `rate` is per year, then
+        precisely a year is understood to elapse between each cash flow
+        event).  By convention, investments or "deposits" are negative,
+        income or "withdrawals" are positive; `values` must begin with
+        the initial investment, thus `values[0]` will typically be
+        negative.
 
     Returns
     -------
@@ -440,9 +584,21 @@ def npv(rate, values):
 
     Notes
     -----
-    Returns the result of:
+    Returns the result of: [G]_
+
+    .. math :: \\sum_{t=0}^M{\\frac{values_t}{(1+rate)^{t}}}
+
+    References
+    ----------
+    .. [G] L. J. Gitman, "Principles of Managerial Finance, Brief," 3rd ed.,
+       Addison-Wesley, 2003, pg. 346.
+
+    Examples
+    --------
+    >>> np.npv(0.281,[-100, 39, 59, 55, 20])
+    -0.0066187288356340801
 
-    .. math :: \\sum_{t=1}^M{\\frac{values_t}{(1+rate)^{t}}}
+    (Compare with the Example given for numpy.lib.financial.irr)
 
     """
     values = np.asarray(values)
diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index b493801df..e596d8810 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -717,9 +717,9 @@ def piecewise(x, condlist, funclist, *args, **kw):
 
     Parameters
     ----------
-    x : (N,) ndarray
+    x : ndarray
         The input domain.
-    condlist : list of M (N,)-shaped boolean arrays
+    condlist : list of bool arrays
         Each boolean array corresponds to a function in `funclist`.  Wherever
         `condlist[i]` is True, `funclist[i](x)` is used as the output value.
 
@@ -727,24 +727,24 @@ def piecewise(x, condlist, funclist, *args, **kw):
         and should therefore be of the same shape as `x`.
 
         The length of `condlist` must correspond to that of `funclist`.
-        If one extra function is given, i.e. if the length of `funclist` is
-        M+1, then that extra function is the default value, used wherever
-        all conditions are false.
-    funclist : list of M or M+1 callables, f(x,*args,**kw), or values
+        If one extra function is given, i.e. if
+        ``len(funclist) - len(condlist) == 1``, then that extra function
+        is the default value, used wherever all conditions are false.
+    funclist : list of callables, f(x,*args,**kw), or scalars
         Each function is evaluated over `x` wherever its corresponding
         condition is True.  It should take an array as input and give an array
         or a scalar value as output.  If, instead of a callable,
-        a value is provided then a constant function (``lambda x: value``) is
+        a scalar is provided then a constant function (``lambda x: scalar``) is
         assumed.
     args : tuple, optional
         Any further arguments given to `piecewise` are passed to the functions
-        upon execution, i.e., if called ``piecewise(...,...,1,'a')``, then
-        each function is called as ``f(x,1,'a')``.
-    kw : dictionary, optional
+        upon execution, i.e., if called ``piecewise(..., ..., 1, 'a')``, then
+        each function is called as ``f(x, 1, 'a')``.
+    kw : dict, optional
         Keyword arguments used in calling `piecewise` are passed to the
         functions upon execution, i.e., if called
-        ``piecewise(...,...,lambda=1)``, then each function is called as
-        ``f(x,lambda=1)``.
+        ``piecewise(..., ..., lambda=1)``, then each function is called as
+        ``f(x, lambda=1)``.
 
     Returns
     -------
@@ -754,6 +754,11 @@ def piecewise(x, condlist, funclist, *args, **kw):
         as defined by the boolean arrays in `condlist`.  Portions not covered
         by any condition have undefined values.
 
+
+    See Also
+    --------
+    choose, select, where
+
     Notes
     -----
     This is similar to choose or select, except that functions are
@@ -773,8 +778,8 @@ def piecewise(x, condlist, funclist, *args, **kw):
     --------
     Define the sigma function, which is -1 for ``x < 0`` and +1 for ``x >= 0``.
 
-    >>> x = np.arange(6) - 2.5 # x runs from -2.5 to 2.5 in steps of 1
-    >>> np.piecewise(x, [x < 0, x >= 0.5], [-1,1])
+    >>> x = np.arange(6) - 2.5
+    >>> np.piecewise(x, [x < 0, x >= 0], [-1, 1])
     array([-1., -1., -1.,  1.,  1.,  1.])
 
     Define the absolute value, which is ``-x`` for ``x <0`` and ``x`` for
@@ -836,39 +841,35 @@ def select(condlist, choicelist, default=0):
 
     Parameters
     ----------
-    condlist : list of N boolean arrays of length M
-            The conditions C_0 through C_(N-1) which determine
-            from which vector the output elements are taken.
-    choicelist : list of N arrays of length M
-            Th vectors V_0 through V_(N-1), from which the output
-            elements are chosen.
+    condlist : list of bool ndarrays
+        The list of conditions which determine from which array in `choicelist`
+        the output elements are taken. When multiple conditions are satisfied,
+        the first one encountered in `condlist` is used.
+    choicelist : list of ndarrays
+        The list of arrays from which the output elements are taken. It has
+        to be of the same length as `condlist`.
+    default : scalar, optional
+        The element inserted in `output` when all conditions evaluate to False.
 
     Returns
     -------
-    output : 1-dimensional array of length M
-            The output at position m is the m-th element of the first
-            vector V_n for which C_n[m] is non-zero.  Note that the
-            output depends on the order of conditions, since the
-            first satisfied condition is used.
-
-    Notes
-    -----
-    Equivalent to:
-    ::
+    output : ndarray
+        The output at position m is the m-th element of the array in
+        `choicelist` where the m-th element of the corresponding array in
+        `condlist` is True.
 
-                output = []
-                for m in range(M):
-                    output += [V[m] for V,C in zip(values,cond) if C[m]]
-                              or [default]
+    See Also
+    --------
+    where : Return elements from one of two arrays depending on condition.
+    take, choose, compress, diag, diagonal
 
     Examples
     --------
-    >>> t = np.arange(10)
-    >>> s = np.arange(10)*100
-    >>> condlist = [t == 4, t > 5]
-    >>> choicelist = [s, t]
+    >>> x = np.arange(10)
+    >>> condlist = [x<3, x>5]
+    >>> choicelist = [x, x**2]
     >>> np.select(condlist, choicelist)
-    array([  0,   0,   0,   0, 400,   0,   6,   7,   8,   9])
+    array([ 0,  1,  2,  0,  0,  0, 36, 49, 64, 81])
 
     """
     n = len(condlist)
@@ -960,11 +961,17 @@ def gradient(f, *varargs):
 
     Examples
     --------
-    >>> np.gradient(np.array([[1,1],[3,4]]))
-    [array([[ 2.,  3.],
-           [ 2.,  3.]]),
-     array([[ 0.,  0.],
-           [ 1.,  1.]])]
+    >>> x = np.array([1, 2, 4, 7, 11, 16], dtype=np.float)
+    >>> np.gradient(x)
+    array([ 1. ,  1.5,  2.5,  3.5,  4.5,  5. ])
+    >>> np.gradient(x, 2)
+    array([ 0.5 ,  0.75,  1.25,  1.75,  2.25,  2.5 ])
+
+    >>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=np.float))
+    [array([[ 2.,  2., -1.],
+           [ 2.,  2., -1.]]),
+    array([[ 1. ,  2.5,  4. ],
+           [ 1. ,  1. ,  1. ]])]
 
     """
     N = len(f.shape)  # number of dimensions
@@ -1026,7 +1033,11 @@ def gradient(f, *varargs):
 
 def diff(a, n=1, axis=-1):
     """
-    Calculate the nth order discrete difference along given axis.
+    Calculate the n-th order discrete difference along given axis.
+
+    The first order difference is given by ``out[n] = a[n+1] - a[n]`` along
+    the given axis, higher order differences are calculated by using `diff`
+    recursively.
 
     Parameters
     ----------
@@ -1035,26 +1046,31 @@ def diff(a, n=1, axis=-1):
     n : int, optional
         The number of times values are differenced.
     axis : int, optional
-        The axis along which the difference is taken.
+        The axis along which the difference is taken, default is the last axis.
 
     Returns
     -------
     out : ndarray
-        The `n` order differences.  The shape of the output is the same as `a`
-        except along `axis` where the dimension is `n` less.
+        The `n` order differences. The shape of the output is the same as `a`
+        except along `axis` where the dimension is smaller by `n`.
+
+    See Also
+    --------
+    gradient, ediff1d
 
     Examples
     --------
-    >>> x = np.array([0,1,3,9,5,10])
+    >>> x = np.array([1, 2, 4, 7, 0])
     >>> np.diff(x)
-    array([ 1,  2,  6, -4,  5])
-    >>> np.diff(x,n=2)
-    array([  1,   4, -10,   9])
-    >>> x = np.array([[1,3,6,10],[0,5,6,8]])
+    array([ 1,  2,  3, -7])
+    >>> np.diff(x, n=2)
+    array([  1,   1, -10])
+
+    >>> x = np.array([[1, 3, 6, 10], [0, 5, 6, 8]])
     >>> np.diff(x)
     array([[2, 3, 4],
-    [5, 1, 2]])
-    >>> np.diff(x,axis=0)
+           [5, 1, 2]])
+    >>> np.diff(x, axis=0)
     array([[-1,  2,  0, -2]])
 
     """
@@ -1201,15 +1217,34 @@ def unwrap(p, discont=pi, axis=-1):
     ----------
     p : array_like
         Input array.
-    discont : float
-        Maximum discontinuity between values.
-    axis : integer
-        Axis along which unwrap will operate.
+    discont : float, optional
+        Maximum discontinuity between values, default is ``pi``.
+    axis : int, optional
+        Axis along which unwrap will operate, default is the last axis.
 
     Returns
     -------
     out : ndarray
-        Output array
+        Output array.
+
+    See Also
+    --------
+    rad2deg, deg2rad
+
+    Notes
+    -----
+    If the discontinuity in `p` is smaller than ``pi``, but larger than
+    `discont`, no unwrapping is done because taking the 2*pi complement
+    would only make the discontinuity larger.
+
+    Examples
+    --------
+    >>> phase = np.linspace(0, np.pi, num=5)
+    >>> phase[3:] += np.pi
+    >>> phase
+    array([ 0.        ,  0.78539816,  1.57079633,  5.49778714,  6.28318531])
+    >>> np.unwrap(phase)
+    array([ 0.        ,  0.78539816,  1.57079633, -0.78539816,  0.        ])
 
     """
     p = asarray(p)
@@ -1365,53 +1400,64 @@ def extract(condition, arr):
 
     See Also
     --------
-    take, put, putmask
+    take, put, putmask, compress
 
     Examples
     --------
-    >>> arr = np.array([[1,2,3,4],[5,6,7,8],[9,10,11,12]])
+    >>> arr = np.arange(12).reshape((3, 4))
     >>> arr
-    array([[ 1,  2,  3,  4],
-           [ 5,  6,  7,  8],
-           [ 9, 10, 11, 12]])
+    array([[ 0,  1,  2,  3],
+           [ 4,  5,  6,  7],
+           [ 8,  9, 10, 11]])
     >>> condition = np.mod(arr, 3)==0
     >>> condition
-    array([[False, False,  True, False],
-           [False,  True, False, False],
-           [ True, False, False,  True]], dtype=bool)
+    array([[ True, False, False,  True],
+           [False, False,  True, False],
+           [False,  True, False, False]], dtype=bool)
     >>> np.extract(condition, arr)
-    array([ 3,  6,  9, 12])
+    array([0, 3, 6, 9])
+
 
     If `condition` is boolean:
 
     >>> arr[condition]
-    array([ 3,  6,  9, 12])
+    array([0, 3, 6, 9])
 
     """
     return _nx.take(ravel(arr), nonzero(ravel(condition))[0])
 
 def place(arr, mask, vals):
     """
-    Changes elements of an array based on conditional and input values.
+    Change elements of an array based on conditional and input values.
 
-    Similar to ``putmask(a, mask, vals)`` but the 1D array `vals` has the
-    same number of elements as the non-zero values of `mask`. Inverse of
-    ``extract``.
+    Similar to ``np.putmask(a, mask, vals)``, the difference is that `place`
+    uses the first N elements of `vals`, where N is the number of True values
+    in `mask`, while `putmask` uses the elements where `mask` is True.
 
-    Sets `a`.flat[n] = `values`\\[n] for each n where `mask`.flat[n] is true.
+    Note that `extract` does the exact opposite of `place`.
 
     Parameters
     ----------
     a : array_like
         Array to put data into.
     mask : array_like
-        Boolean mask array.
-    values : array_like, shape(number of non-zero `mask`, )
-        Values to put into `a`.
+        Boolean mask array. Must have the same size as `a`.
+    vals : 1-D sequence
+        Values to put into `a`. Only the first N elements are used, where
+        N is the number of True values in `mask`. If `vals` is smaller
+        than N it will be repeated.
 
     See Also
     --------
-    putmask, put, take
+    putmask, put, take, extract
+
+    Examples
+    --------
+    >>> x = np.arange(6).reshape(2, 3)
+    >>> np.place(x, x>2, [44, 55])
+    >>> x
+    array([[ 0,  1,  2],
+           [44, 55, 44]])
 
     """
     return _insert(arr, mask, vals)
@@ -2841,6 +2887,25 @@ def trapz(y, x=None, dx=1.0, axis=-1):
     axis : int, optional
         Specify the axis.
 
+    Returns
+    -------
+    out : float
+        Definite integral as approximated by trapezoidal rule.
+
+    Notes
+    -----
+    Image [2]_ illustrates trapezoidal rule -- y-axis locations of points will
+    be taken from `y` array, by default x-axis distances between points will be
+    1.0, alternatively they can be provided with `x` array or with `dx` scalar.
+    Return value will be equal to combined area under the red lines.
+
+
+    References
+    ----------
+    .. [1] Wikipedia page: http://en.wikipedia.org/wiki/Trapezoidal_rule
+
+    .. [2] Illustration image: http://en.wikipedia.org/wiki/File:Composite_trapezoidal_rule_illustration.png
+
     Examples
     --------
     >>> np.trapz([1,2,3])
diff --git a/numpy/lib/index_tricks.py b/numpy/lib/index_tricks.py
index b8add9ed7..b6eaae29f 100644
--- a/numpy/lib/index_tricks.py
+++ b/numpy/lib/index_tricks.py
@@ -18,14 +18,20 @@ makemat = matrix.matrix
 # contributed by Stefan van der Walt
 def unravel_index(x,dims):
     """
-    Convert a flat index into an index tuple for an array of given shape.
+    Convert a flat index to an index tuple for an array of given shape.
 
     Parameters
     ----------
     x : int
         Flattened index.
-    dims : shape tuple
-        Input shape.
+    dims : tuple of ints
+        Input shape, the shape of an array into which indexing is
+        required.
+
+    Returns
+    -------
+    idx : tuple of ints
+        Tuple of the same shape as `dims`, containing the unraveled index.
 
     Notes
     -----
@@ -34,7 +40,7 @@ def unravel_index(x,dims):
 
     Examples
     --------
-    >>> arr = np.arange(20).reshape(5,4)
+    >>> arr = np.arange(20).reshape(5, 4)
     >>> arr
     array([[ 0,  1,  2,  3],
            [ 4,  5,  6,  7],
@@ -72,21 +78,45 @@ def unravel_index(x,dims):
     return tuple(x/dim_prod % dims)
 
 def ix_(*args):
-    """ Construct an open mesh from multiple sequences.
+    """
+    Construct an open mesh from multiple sequences.
+
+    This function takes N 1-D sequences and returns N outputs with N
+    dimensions each, such that the shape is 1 in all but one dimension
+    and the dimension with the non-unit shape value cycles through all
+    N dimensions.
+
+    Using `ix_` one can quickly construct index arrays that will index
+    the cross product. ``a[np.ix_([1,3],[2,5])]`` returns the array
+    ``[a[1,2] a[1,5] a[3,2] a[3,5]]``.
+
+    Parameters
+    ----------
+    args : 1-D sequences
 
-    This function takes n 1-d sequences and returns n outputs with n
-    dimensions each such that the shape is 1 in all but one dimension and
-    the dimension with the non-unit shape value cycles through all n
-    dimensions.
+    Returns
+    -------
+    out : ndarrays
+        N arrays with N dimensions each, with N the number of input
+        sequences. Together these arrays form an open mesh.
 
-    Using ix_() one can quickly construct index arrays that will index
-    the cross product.
+    See Also
+    --------
+    ogrid, mgrid, meshgrid
 
-    a[ix_([1,3,7],[2,5,8])]  returns the array
+    Examples
+    --------
+    >>> a = np.arange(10).reshape(2, 5)
+    >>> ixgrid = np.ix_([0,1], [2,4])
+    >>> ixgrid
+    (array([[0],
+           [1]]), array([[2, 4]]))
+    >>> print ixgrid[0].shape, ixgrid[1].shape
+    (2, 1) (1, 2)
+    >>> a[ixgrid]
+    array([[2, 4],
+           [7, 9]])
 
-    a[1,2]  a[1,5]  a[1,8]
-    a[3,2]  a[3,5]  a[3,8]
-    a[7,2]  a[7,5]  a[7,8]
     """
     out = []
     nd = len(args)
@@ -215,7 +245,11 @@ mgrid.__doc__ = None # set in numpy.add_newdocs
 ogrid.__doc__ = None # set in numpy.add_newdocs
 
 class AxisConcatenator(object):
-    """Translates slice objects to concatenation along an axis.
+    """
+    Translates slice objects to concatenation along an axis.
+
+    For detailed documentation on usage, see `r_`.
+
     """
     def _retval(self, res):
         if self.matrix:
@@ -338,11 +372,96 @@ class AxisConcatenator(object):
 # in help(r_)
 
 class RClass(AxisConcatenator):
-    """Translates slice objects to concatenation along the first axis.
+    """
+    Translates slice objects to concatenation along the first axis.
+
+    This is a simple way to build up arrays quickly. There are two use cases.
+
+    1. If the index expression contains comma separated arrays, then stack
+       them along their first axis.
+    2. If the index expression contains slice notation or scalars then create
+       a 1-D array with a range indicated by the slice notation.
+
+    If slice notation is used, the syntax ``start:stop:step`` is equivalent
+    to ``np.arange(start, stop, step)`` inside of the brackets. However, if
+    ``step`` is an imaginary number (i.e. 100j) then its integer portion is
+    interpreted as a number-of-points desired and the start and stop are
+    inclusive. In other words ``start:stop:stepj`` is interpreted as
+    ``np.linspace(start, stop, step, endpoint=1)`` inside of the brackets.
+    After expansion of slice notation, all comma separated sequences are
+    concatenated together.
+
+    Optional character strings placed as the first element of the index
+    expression can be used to change the output. The strings 'r' or 'c' result
+    in matrix output. If the result is 1-D and 'r' is specified a 1 x N (row)
+    matrix is produced. If the result is 1-D and 'c' is specified, then a N x 1
+    (column) matrix is produced. If the result is 2-D then both provide the
+    same matrix result.
+
+    A string integer specifies which axis to stack multiple comma separated
+    arrays along. A string of two comma-separated integers allows indication
+    of the minimum number of dimensions to force each entry into as the
+    second integer (the axis to concatenate along is still the first integer).
+
+    A string with three comma-separated integers allows specification of the
+    axis to concatenate along, the minimum number of dimensions to force the
+    entries to, and which axis should contain the start of the arrays which
+    are less than the specified number of dimensions. In other words the third
+    integer allows you to specify where the 1's should be placed in the shape
+    of the arrays that have their shapes upgraded. By default, they are placed
+    in the front of the shape tuple. The third argument allows you to specify
+    where the start of the array should be instead. Thus, a third argument of
+    '0' would place the 1's at the end of the array shape. Negative integers
+    specify where in the new shape tuple the last dimension of upgraded arrays
+    should be placed, so the default is '-1'.
+
+    Parameters
+    ----------
+    Not a function, so takes no parameters
+
+
+    Returns
+    -------
+    A concatenated ndarray or matrix.
+
+    See Also
+    --------
+    concatenate : Join a sequence of arrays together.
+    c_ : Translates slice objects to concatenation along the second axis.
 
-    For example:
+    Examples
+    --------
     >>> np.r_[np.array([1,2,3]), 0, 0, np.array([4,5,6])]
     array([1, 2, 3, 0, 0, 4, 5, 6])
+    >>> np.r_[-1:1:6j, [0]*3, 5, 6]
+    array([-1. , -0.6, -0.2,  0.2,  0.6,  1. ,  0. ,  0. ,  0. ,  5. ,  6. ])
+
+    String integers specify the axis to concatenate along or the minimum
+    number of dimensions to force entries into.
+
+    >>> np.r_['-1', a, a] # concatenate along last axis
+    array([[0, 1, 2, 0, 1, 2],
+           [3, 4, 5, 3, 4, 5]])
+    >>> np.r_['0,2', [1,2,3], [4,5,6]] # concatenate along first axis, dim>=2
+    array([[1, 2, 3],
+           [4, 5, 6]])
+
+    >>> np.r_['0,2,0', [1,2,3], [4,5,6]]
+    array([[1],
+           [2],
+           [3],
+           [4],
+           [5],
+           [6]])
+    >>> np.r_['1,2,0', [1,2,3], [4,5,6]]
+    array([[1, 4],
+           [2, 5],
+           [3, 6]])
+
+    Using 'r' or 'c' as a first string argument creates a matrix.
+
+    >>> np.r_['r',[1,2,3], [4,5,6]]
+    matrix([[1, 2, 3, 4, 5, 6]])
 
     """
     def __init__(self):
@@ -351,11 +470,21 @@ class RClass(AxisConcatenator):
 r_ = RClass()
 
 class CClass(AxisConcatenator):
-    """Translates slice objects to concatenation along the second axis.
+    """
+    Translates slice objects to concatenation along the second axis.
+
+    This is short-hand for ``np.r_['-1,2,0', index expression]``, which is
+    useful because of its common occurrence. In particular, arrays will be
+    stacked along their last axis after being upgraded to at least 2-D with
+    1's post-pended to the shape (column vectors made out of 1-D arrays).
 
-    For example:
+    For detailed documentation, see `r_`.
+
+    Examples
+    --------
     >>> np.c_[np.array([[1,2,3]]), 0, 0, np.array([[4,5,6]])]
-    array([1, 2, 3, 0, 0, 4, 5, 6])
+    array([[1, 2, 3, 0, 0, 4, 5, 6]])
+
     """
     def __init__(self):
         AxisConcatenator.__init__(self, -1, ndmin=2, trans1d=0)
@@ -373,9 +502,13 @@ class ndenumerate(object):
     a : ndarray
       Input array.
 
+    See Also
+    --------
+    ndindex, flatiter
+
     Examples
     --------
-    >>> a = np.array([[1,2],[3,4]])
+    >>> a = np.array([[1, 2], [3, 4]])
     >>> for index, x in np.ndenumerate(a):
     ...     print index, x
     (0, 0) 1
@@ -388,6 +521,17 @@ class ndenumerate(object):
         self.iter = asarray(arr).flat
 
     def next(self):
+        """
+        Standard iterator method, returns the index tuple and array value.
+
+        Returns
+        -------
+        coords : tuple of ints
+            The indices of the current iteration.
+        val : scalar
+            The array element of the current iteration.
+
+        """
         return self.iter.coords, self.iter.next()
 
     def __iter__(self):
@@ -399,17 +543,21 @@ class ndindex(object):
     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.
+    the N-dimensional index of the array. At each iteration a tuple
+    of indices is returned, the last dimension is iterated over first.
 
     Parameters
     ----------
-    `*args` : integers
-      The size of each dimension in the counter.
+    `*args` : ints
+      The size of each dimension of the array.
+
+    See Also
+    --------
+    ndenumerate, flatiter
 
     Examples
     --------
-    >>> for index in np.ndindex(3,2,1):
+    >>> for index in np.ndindex(3, 2, 1):
     ...     print index
     (0, 0, 0)
     (0, 1, 0)
@@ -442,9 +590,25 @@ class ndindex(object):
             self._incrementone(axis-1)
 
     def ndincr(self):
+        """
+        Increment the multi-dimensional index by one.
+
+        `ndincr` takes care of the "wrapping around" of the axes.
+        It is called by `ndindex.next` and not normally used directly.
+
+        """
         self._incrementone(self.nd-1)
 
     def next(self):
+        """
+        Standard iterator method, updates the index and returns the index tuple.
+
+        Returns
+        -------
+        val : tuple of ints
+            Returns a tuple containing the indices of the current iteration.
+
+        """
         if (self.index >= self.total):
             raise StopIteration
         val = tuple(self.ind)
diff --git a/numpy/lib/io.py b/numpy/lib/io.py
index 98d071fab..3464b568c 100644
--- a/numpy/lib/io.py
+++ b/numpy/lib/io.py
@@ -126,6 +126,7 @@ def load(file, mmap_mode=None):
     ----------
     file : file-like object or string
         The file to read.  It must support ``seek()`` and ``read()`` methods.
+        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
@@ -146,6 +147,11 @@ def load(file, mmap_mode=None):
     IOError
         If the input file does not exist or cannot be read.
 
+    See Also
+    --------
+    save, savez, loadtxt
+    memmap : Create a memory-map to an array stored in a file on disk.
+
     Notes
     -----
     - If the file contains pickle data, then whatever is stored in the
@@ -202,20 +208,20 @@ def load(file, mmap_mode=None):
 
 def save(file, arr):
     """
-    Save an array to a binary file in NumPy format.
+    Save an array to a binary file in NumPy ``.npy`` format.
 
     Parameters
     ----------
-    f : file or string
+    file : file or string
         File or filename to which the data is saved.  If the filename
         does not already have a ``.npy`` extension, it is added.
-    x : array_like
-        Array data.
+    arr : array_like
+        Array data to be saved.
 
     See Also
     --------
-    savez : Save several arrays into an .npz compressed archive
-    savetxt : Save an array to a file as plain text
+    savez : Save several arrays into a .npz compressed archive
+    savetxt, load
 
     Examples
     --------
@@ -225,7 +231,7 @@ def save(file, arr):
     >>> x = np.arange(10)
     >>> np.save(outfile, x)
 
-    >>> outfile.seek(0)
+    >>> outfile.seek(0) # only necessary in this example (with tempfile)
     >>> np.load(outfile)
     array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
 
@@ -523,20 +529,20 @@ def loadtxt(fname, dtype=float, comments='#', delimiter=None, converters=None,
 
 def savetxt(fname, X, fmt='%.18e',delimiter=' '):
     """
-    Save an array to file.
+    Save an array to a text file.
 
     Parameters
     ----------
-    fname : filename or a file handle
-        If the filename ends in .gz, the file is automatically saved in
-        compressed gzip format.  The load() command understands gzipped
-        files transparently.
+    fname : filename or file handle
+        If the filename ends in ``.gz``, the file is automatically saved in
+        compressed gzip format.  `loadtxt` understands gzipped files
+        transparently.
     X : array_like
-        Data.
-    fmt : string or sequence of strings
+        Data to be saved to a text file.
+    fmt : str or sequence of strs
         A single format (%10.5f), a sequence of formats, or a
         multi-format string, e.g. 'Iteration %d -- %10.5f', in which
-        case delimiter is ignored.
+        case `delimiter` is ignored.
     delimiter : str
         Character separating columns.
 
@@ -588,15 +594,20 @@ def savetxt(fname, X, fmt='%.18e',delimiter=' '):
 
         ``x,X`` : unsigned hexadecimal integer
 
-    This is not an exhaustive specification.
-
+    This explanation of ``fmt`` is not complete, for an exhaustive
+    specification see [1]_.
 
+    References
+    ----------
+    .. [1] `Format Specification Mini-Language
+           <http://docs.python.org/library/string.html#
+           format-specification-mini-language>`_, Python Documentation.
 
     Examples
     --------
-    >>> savetxt('test.out', x, delimiter=',') # X is an array
-    >>> savetxt('test.out', (x,y,z)) # x,y,z equal sized 1D arrays
-    >>> savetxt('test.out', x, fmt='%1.4e') # use exponential notation
+    >>> savetxt('test.out', x, delimiter=',')   # X is an array
+    >>> savetxt('test.out', (x,y,z))   # x,y,z equal sized 1D arrays
+    >>> savetxt('test.out', x, fmt='%1.4e')   # use exponential notation
 
     """
 
@@ -712,15 +723,13 @@ def genfromtxt(fname, dtype=float, comments='#', delimiter=None, skiprows=0,
 
     Each line past the first `skiprows` ones is split at the `delimiter`
     character, and characters following the `comments` character are discarded.
-    
-
 
     Parameters
     ----------
-    fname : file or string
-        File or filename to read.  If the filename extension is `.gz` or `.bz2`,
-        the file is first decompressed.
-    dtype : data-type
+    fname : {file, string}
+        File or filename to read.  If the filename extension is `.gz` or
+        `.bz2`, the file is first decompressed.
+    dtype : dtype
         Data type of the resulting array.  If this is a flexible data-type,
         the resulting array will be 1-dimensional, and each row will be
         interpreted as an element of the array. In this case, the number
@@ -729,20 +738,20 @@ def genfromtxt(fname, dtype=float, comments='#', delimiter=None, skiprows=0,
         of the dtype.
         If None, the dtypes will be determined by the contents of each
         column, individually.
-    comments : {string}, optional
+    comments : string, optional
         The character used to indicate the start of a comment.
         All the characters occurring on a line after a comment are discarded
-    delimiter : {string}, optional
+    delimiter : string, optional
         The string used to separate values.  By default, any consecutive
         whitespace act as delimiter.
-    skiprows : {int}, optional
+    skiprows : int, optional
         Numbers of lines to skip at the beginning of the file.
     converters : {None, dictionary}, optional
         A dictionary mapping column number to a function that will convert
         values in the column to a number. Converters can also be used to
         provide a default value for missing data:
         ``converters = {3: lambda s: float(s or 0)}``.
-    missing : {string}, optional
+    missing : string, optional
         A string representing a missing value, irrespective of the column where
         it appears (e.g., `'missing'` or `'unused'`).
     missing_values : {None, dictionary}, optional
@@ -757,20 +766,21 @@ def genfromtxt(fname, dtype=float, comments='#', delimiter=None, skiprows=0,
         If `names` is a sequence or a single-string of comma-separated names,
         the names will be used to define the field names in a flexible dtype.
         If `names` is None, the names of the dtype fields will be used, if any.
-    excludelist : {sequence}, optional
+    excludelist : sequence, optional
         A list of names to exclude. This list is appended to the default list
         ['return','file','print']. Excluded names are appended an underscore:
         for example, `file` would become `file_`.
-    deletechars : {string}, optional
-        A string combining invalid characters that must be deleted from the names.
+    deletechars : string, optional
+        A string combining invalid characters that must be deleted from the
+        names.
     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.
         If 'lower', field names are converted to lower case.
-    unpack : {bool}, optional
+    unpack : bool, optional
         If True, the returned array is transposed, so that arguments may be
         unpacked using ``x, y, z = loadtxt(...)``
-    usemask : {bool}, optional
+    usemask : bool, optional
         If True, returns a masked array.
         If False, return a regular standard array.
 
@@ -779,23 +789,20 @@ def genfromtxt(fname, dtype=float, comments='#', delimiter=None, skiprows=0,
     out : MaskedArray
         Data read from the text file.
 
-    Notes
+    See Also
     --------
+    numpy.loadtxt : equivalent function when no data is missing.
+
+    Notes
+    -----
     * When spaces are used as delimiters, or when no delimiter has been given
       as input, there should not be any missing data between two fields.
     * When the variable are named (either by a flexible dtype or with `names`,
-      there must not be any header in the file (else a :exc:ValueError exception
-      is raised).
-
-    Warnings
-    --------
+      there must not be any header in the file (else a :exc:ValueError
+      exception is raised).
     * Individual values are not stripped of spaces by default.
       When using a custom converter, make sure the function does remove spaces.
 
-    See Also
-    --------
-    numpy.loadtxt : equivalent function when no data is missing.
-
     """
     #
     if usemask:
@@ -1128,20 +1135,21 @@ def recfromtxt(fname, dtype=None, comments='#', delimiter=None, skiprows=0,
                excludelist=None, deletechars=None, case_sensitive=True,
                usemask=False):
     """
-    Load ASCII data stored in fname and returns a standard recarray (if 
+    Load ASCII data stored in fname and returns a standard recarray (if
     `usemask=False`) or a MaskedRecords (if `usemask=True`).
-    
+
     Complete description of all the optional input parameters is available in
     the docstring of the `genfromtxt` function.
-    
+
     See Also
     --------
     numpy.genfromtxt : generic function
 
-    Warnings
-    --------
+    Notes
+    -----
     * by default, `dtype=None`, which means that the dtype of the output array
       will be determined from the data.
+
     """
     kwargs = dict(dtype=dtype, comments=comments, delimiter=delimiter, 
                   skiprows=skiprows, converters=converters,
diff --git a/numpy/lib/scimath.py b/numpy/lib/scimath.py
index 269d332bf..0e1bafa91 100644
--- a/numpy/lib/scimath.py
+++ b/numpy/lib/scimath.py
@@ -166,7 +166,8 @@ def _fix_real_abs_gt_1(x):
     return x
 
 def sqrt(x):
-    """Return the square root of x.
+    """
+    Return the square root of x.
 
     Parameters
     ----------
@@ -174,12 +175,29 @@ def sqrt(x):
 
     Returns
     -------
-    array_like output.
+    out : array_like
+
+    Notes
+    -----
+
+    As the numpy.sqrt, this returns the principal square root of x, which is
+    what most people mean when they use square root; the principal square root
+    of x is not any number z such as z^2 = x.
+
+    For positive numbers, the principal square root is defined as the positive
+    number z such as z^2 = x.
+
+    The principal square root of -1 is i, the principal square root of any
+    negative number -x is defined a i * sqrt(x). For any non zero complex
+    number, it is defined by using the following branch cut: x = r e^(i t) with
+    r > 0 and -pi < t <= pi. The principal square root is then
+    sqrt(r) e^(i t/2).
 
     Examples
     --------
 
     For real, non-negative inputs this works just like numpy.sqrt():
+
     >>> np.lib.scimath.sqrt(1)
     1.0
 
@@ -187,33 +205,20 @@ def sqrt(x):
     array([ 1.,  2.])
 
     But it automatically handles negative inputs:
+
     >>> np.lib.scimath.sqrt(-1)
     (0.0+1.0j)
 
     >>> np.lib.scimath.sqrt([-1,4])
     array([ 0.+1.j,  2.+0.j])
 
-    Notes
-    -----
-
-    As the numpy.sqrt, this returns the principal square root of x, which is
-    what most people mean when they use square root; the principal square root
-    of x is not any number z such as z^2 = x.
-
-    For positive numbers, the principal square root is defined as the positive
-    number z such as z^2 = x.
-
-    The principal square root of -1 is i, the principal square root of any
-    negative number -x is defined a i * sqrt(x). For any non zero complex
-    number, it is defined by using the following branch cut: x = r e^(i t) with
-    r > 0 and -pi < t <= pi. The principal square root is then
-    sqrt(r) e^(i t/2).
     """
     x = _fix_real_lt_zero(x)
     return nx.sqrt(x)
 
 def log(x):
-    """Return the natural logarithm of x.
+    """
+    Return the natural logarithm of x.
 
     If x contains negative inputs, the answer is computed and returned in the
     complex domain.
@@ -224,7 +229,7 @@ def log(x):
 
     Returns
     -------
-    array_like
+    out : array_like
 
     Examples
     --------
@@ -237,12 +242,14 @@ def log(x):
 
     >>> np.lib.scimath.log(-math.exp(1)) == (1+1j*math.pi)
     True
+
     """
     x = _fix_real_lt_zero(x)
     return nx.log(x)
 
 def log10(x):
-    """Return the base 10 logarithm of x.
+    """
+    Return the base 10 logarithm of x.
 
     If x contains negative inputs, the answer is computed and returned in the
     complex domain.
@@ -253,12 +260,13 @@ def log10(x):
 
     Returns
     -------
-    array_like
+    out : array_like
 
     Examples
     --------
 
     (We set the printing precision so the example can be auto-tested)
+
     >>> np.set_printoptions(precision=4)
 
     >>> np.lib.scimath.log10([10**1,10**2])
@@ -267,12 +275,14 @@ def log10(x):
 
     >>> np.lib.scimath.log10([-10**1,-10**2,10**2])
     array([ 1.+1.3644j,  2.+1.3644j,  2.+0.j    ])
+
     """
     x = _fix_real_lt_zero(x)
     return nx.log10(x)
 
 def logn(n, x):
-    """Take log base n of x.
+    """
+    Take log base n of x.
 
     If x contains negative inputs, the answer is computed and returned in the
     complex domain.
@@ -283,12 +293,13 @@ def logn(n, x):
 
     Returns
     -------
-    array_like
+    out : array_like
 
     Examples
     --------
 
     (We set the printing precision so the example can be auto-tested)
+
     >>> np.set_printoptions(precision=4)
 
     >>> np.lib.scimath.logn(2,[4,8])
@@ -296,13 +307,15 @@ def logn(n, x):
 
     >>> np.lib.scimath.logn(2,[-4,-8,8])
     array([ 2.+4.5324j,  3.+4.5324j,  3.+0.j    ])
+
     """
     x = _fix_real_lt_zero(x)
     n = _fix_real_lt_zero(n)
     return nx.log(x)/nx.log(n)
 
 def log2(x):
-    """ Take log base 2 of x.
+    """
+    Take log base 2 of x.
 
     If x contains negative inputs, the answer is computed and returned in the
     complex domain.
@@ -313,12 +326,13 @@ def log2(x):
 
     Returns
     -------
-    array_like
+    out : array_like
 
     Examples
     --------
 
     (We set the printing precision so the example can be auto-tested)
+
     >>> np.set_printoptions(precision=4)
 
     >>> np.lib.scimath.log2([4,8])
@@ -326,12 +340,14 @@ def log2(x):
 
     >>> np.lib.scimath.log2([-4,-8,8])
     array([ 2.+4.5324j,  3.+4.5324j,  3.+0.j    ])
+
     """
     x = _fix_real_lt_zero(x)
     return nx.log2(x)
 
 def power(x, p):
-    """Return x**p.
+    """
+    Return x**p.
 
     If x contains negative values, it is converted to the complex domain.
 
@@ -344,11 +360,12 @@ def power(x, p):
 
     Returns
     -------
-    array_like
+    out : array_like
 
     Examples
     --------
     (We set the printing precision so the example can be auto-tested)
+
     >>> np.set_printoptions(precision=4)
 
     >>> np.lib.scimath.power([2,4],2)
@@ -359,6 +376,7 @@ def power(x, p):
 
     >>> np.lib.scimath.power([-2,4],2)
     array([  4.+0.j,  16.+0.j])
+
     """
     x = _fix_real_lt_zero(x)
     p = _fix_int_lt_zero(p)
@@ -393,7 +411,8 @@ def arccos(x):
     return nx.arccos(x)
 
 def arcsin(x):
-    """Compute the inverse sine of x.
+    """
+    Compute the inverse sine of x.
 
     For real x with abs(x)<=1, this returns the principal value.
 
@@ -410,6 +429,7 @@ def arcsin(x):
     Examples
     --------
     (We set the printing precision so the example can be auto-tested)
+
     >>> np.set_printoptions(precision=4)
 
     >>> np.lib.scimath.arcsin(0)
@@ -417,12 +437,14 @@ def arcsin(x):
 
     >>> np.lib.scimath.arcsin([0,1])
     array([ 0.    ,  1.5708])
+
     """
     x = _fix_real_abs_gt_1(x)
     return nx.arcsin(x)
 
 def arctanh(x):
-    """Compute the inverse hyperbolic tangent of x.
+    """
+    Compute the inverse hyperbolic tangent of x.
 
     For real x with abs(x)<=1, this returns the principal value.
 
@@ -434,7 +456,7 @@ def arctanh(x):
 
     Returns
     -------
-    array_like
+    out : array_like
 
     Examples
     --------
@@ -446,6 +468,7 @@ def arctanh(x):
 
     >>> np.lib.scimath.arctanh([0,2])
     array([ 0.0000+0.j    ,  0.5493-1.5708j])
+
     """
     x = _fix_real_abs_gt_1(x)
     return nx.arctanh(x)
diff --git a/numpy/lib/shape_base.py b/numpy/lib/shape_base.py
index 19dd54f7a..69ef0be4f 100644
--- a/numpy/lib/shape_base.py
+++ b/numpy/lib/shape_base.py
@@ -1007,6 +1007,19 @@ def tile(A, reps):
     """
     Construct an array by repeating A the number of times given by reps.
 
+    If `reps` has length ``d``, the result will have dimension of
+    ``max(d, A.ndim)``.
+
+    If ``A.ndim < d``, `A` is promoted to be d-dimensional by prepending new
+    axes. So a shape (3,) array is promoted to (1, 3) for 2-D replication,
+    or shape (1, 1, 3) for 3-D replication. If this is not the desired
+    behavior, promote `A` to d-dimensions manually before calling this
+    function.
+
+    If ``A.ndim > d``, `reps` is promoted to `A`.ndim by pre-pending 1's to it.
+    Thus for an `A` of shape (2, 3, 4, 5), a `reps` of (2, 2) is treated as
+    (1, 1, 2, 2).
+
     Parameters
     ----------
     A : array_like
@@ -1017,24 +1030,11 @@ def tile(A, reps):
     Returns
     -------
     c : ndarray
-        The output array.
+        The tiled output array.
 
     See Also
     --------
-    repeat
-
-    Notes
-    -----
-    If `reps` has length d, the result will have dimension of max(d, `A`.ndim).
-
-    If `A`.ndim < d, `A` is promoted to be d-dimensional by prepending new
-    axes. So a shape (3,) array is promoted to (1,3) for 2-D replication,
-    or shape (1,1,3) for 3-D replication. If this is not the desired behavior,
-    promote `A` to d-dimensions manually before calling this function.
-
-    If `A`.ndim > d, `reps` is promoted to `A`.ndim by pre-pending 1's to it.
-    Thus for an `A` of shape (2,3,4,5), a `reps` of (2,2) is treated as
-    (1,1,2,2).
+    repeat : Repeat elements of an array.
 
     Examples
     --------
@@ -1046,7 +1046,6 @@ def tile(A, reps):
            [0, 1, 2, 0, 1, 2]])
     >>> np.tile(a, (2, 1, 2))
     array([[[0, 1, 2, 0, 1, 2]],
-    <BLANKLINE>
            [[0, 1, 2, 0, 1, 2]]])
 
     >>> b = np.array([[1, 2], [3, 4]])
diff --git a/numpy/lib/type_check.py b/numpy/lib/type_check.py
index 113cec682..69f4f2193 100644
--- a/numpy/lib/type_check.py
+++ b/numpy/lib/type_check.py
@@ -85,8 +85,8 @@ def real(val):
     Returns
     -------
     out : ndarray
-        If `val` is real, the type of `val` is used for the output.  If `val`
-        has complex elements, the returned type is float.
+        Output array. If `val` is real, the type of `val` is used for the
+        output.  If `val` has complex elements, the returned type is float.
 
     See Also
     --------
@@ -94,13 +94,13 @@ def real(val):
 
     Examples
     --------
-    >>> a = np.array([1+2j,3+4j,5+6j])
+    >>> a = np.array([1+2j, 3+4j, 5+6j])
     >>> a.real
     array([ 1.,  3.,  5.])
     >>> a.real = 9
     >>> a
     array([ 9.+2.j,  9.+4.j,  9.+6.j])
-    >>> a.real = np.array([9,8,7])
+    >>> a.real = np.array([9, 8, 7])
     >>> a
     array([ 9.+2.j,  8.+4.j,  7.+6.j])
 
@@ -109,7 +109,7 @@ def real(val):
 
 def imag(val):
     """
-    Return the imaginary part of array.
+    Return the imaginary part of the elements of the array.
 
     Parameters
     ----------
@@ -118,8 +118,22 @@ def imag(val):
 
     Returns
     -------
-    out : ndarray, real or int
-        Real part of each element, same shape as `val`.
+    out : ndarray
+        Output array. If `val` is real, the type of `val` is used for the
+        output.  If `val` has complex elements, the returned type is float.
+
+    See Also
+    --------
+    real, angle, real_if_close
+
+    Examples
+    --------
+    >>> a = np.array([1+2j, 3+4j, 5+6j])
+    >>> a.imag
+    array([ 2.,  4.,  6.])
+    >>> a.imag = np.array([8, 10, 12])
+    >>> a
+    array([ 1. +8.j,  3.+10.j,  5.+12.j])
 
     """
     return asanyarray(val).imag
diff --git a/numpy/lib/ufunclike.py b/numpy/lib/ufunclike.py
index 5dbc3f225..5e89b0930 100644
--- a/numpy/lib/ufunclike.py
+++ b/numpy/lib/ufunclike.py
@@ -176,7 +176,7 @@ def isneginf(x, y=None):
 _log2 = nx.log(2)
 def log2(x, y=None):
     """
-    Return the base 2 logarithm.
+    Return the base 2 logarithm of the input array, element-wise.
 
     Parameters
     ----------
@@ -188,7 +188,7 @@ def log2(x, y=None):
     Returns
     -------
     y : ndarray
-      The logarithm to the base 2 of `x` elementwise.
+      The logarithm to the base 2 of `x` element-wise.
       NaNs are returned where `x` is negative.
 
     See Also
@@ -197,7 +197,7 @@ def log2(x, y=None):
 
     Examples
     --------
-    >>> np.log2([-1,2,4])
+    >>> np.log2([-1, 2, 4])
     array([ NaN,   1.,   2.])
 
     """
diff --git a/numpy/lib/utils.py b/numpy/lib/utils.py
index 3de0579df..908c4995d 100644
--- a/numpy/lib/utils.py
+++ b/numpy/lib/utils.py
@@ -81,12 +81,34 @@ else:
         return func
 
 def deprecate(func, oldname=None, newname=None):
-    """Deprecate old functions.
+    """
+    Deprecate old functions.
+
     Issues a DeprecationWarning, adds warning to oldname's docstring,
     rebinds oldname.__name__ and returns new function object.
 
-    Example:
-    oldfunc = deprecate(newfunc, 'oldfunc', 'newfunc')
+    Parameters
+    ----------
+    func : function
+
+    oldname : string
+
+    newname : string
+
+    Returns
+    -------
+    old_func : function
+
+    Examples
+    --------
+    Note that olduint returns a value after printing Deprecation Warning.
+
+    >>> olduint = np.deprecate(np.uint)
+    >>> olduint(6)
+    /usr/lib/python2.5/site-packages/numpy/lib/utils.py:114:
+    DeprecationWarning: uint32 is deprecated
+      warnings.warn(str1, DeprecationWarning)
+    6
 
     """
 
@@ -186,13 +208,28 @@ def byte_bounds(a):
 
 
 def may_share_memory(a, b):
-    """Determine if two arrays can share memory
+    """
+    Determine if two arrays can share memory
 
     The memory-bounds of a and b are computed.  If they overlap then
     this function returns True.  Otherwise, it returns False.
 
     A return of True does not necessarily mean that the two arrays
     share any element.  It just means that they *might*.
+
+    Parameters
+    ----------
+    a, b : ndarray
+
+    Returns
+    -------
+    out : bool
+
+    Examples
+    --------
+    >>> np.may_share_memory(np.array([1,2]), np.array([5,8,9]))
+    False
+
     """
     a_low, a_high = byte_bounds(a)
     b_low, b_high = byte_bounds(b)
@@ -349,24 +386,46 @@ def info(object=None,maxwidth=76,output=sys.stdout,toplevel='numpy'):
 
     Parameters
     ----------
-    object : optional
-        Input object to get information about.
+    object : object or str, optional
+        Input object or name to get information about. If `object` is a
+        numpy object, its docstring is given. If it is a string, available
+        modules are searched for matching objects.
+        If None, information about `info` itself is returned.
     maxwidth : int, optional
         Printing width.
-    output : file like object open for writing, optional
-        Write into file like object.
-    toplevel : string, optional
+    output : file like object, optional
+        File like object that the output is written to, default is ``stdout``.
+        The object has to be opened in 'w' or 'a' mode.
+    toplevel : str, optional
         Start search at this level.
 
+    See Also
+    --------
+    source, lookfor
+
+    Notes
+    -----
+    When used interactively with an object, ``np.info(obj)`` is equivalent to
+    ``help(obj)`` on the Python prompt or ``obj?`` on the IPython prompt.
+
     Examples
     --------
     >>> np.info(np.polyval) # doctest: +SKIP
-
        polyval(p, x)
+         Evaluate the polynomial p at x.
+         ...
 
-         Evaluate the polymnomial p at x.
+    When using a string for `object` it is possible to get multiple results.
 
-         ...
+    >>> np.info('fft') # doctest: +SKIP
+         *** Found in numpy ***
+    Core FFT routines
+    ...
+         *** Found in numpy.fft ***
+     fft(a, n=None, axis=-1)
+    ...
+         *** Repeat reference found in numpy.fft.fftpack ***
+         *** Total of 3 references found. ***
 
     """
     global _namedict, _dictlist
@@ -512,15 +571,39 @@ def source(object, output=sys.stdout):
     """
     Print or write to a file the source code for a Numpy object.
 
+    The source code is only returned for objects written in Python. Many
+    functions and classes are defined in C and will therefore not return
+    useful information.
+
     Parameters
     ----------
     object : numpy object
-        Input object.
+        Input object. This can be any object (function, class, module, ...).
     output : file object, optional
         If `output` not supplied then source code is printed to screen
         (sys.stdout).  File object must be created with either write 'w' or
         append 'a' modes.
 
+    See Also
+    --------
+    lookfor, info
+
+    Examples
+    --------
+    >>> np.source(np.interp)
+    In file: /usr/lib/python2.6/dist-packages/numpy/lib/function_base.py
+    def interp(x, xp, fp, left=None, right=None):
+        \"\"\".... (full docstring printed)\"\"\"
+        if isinstance(x, (float, int, number)):
+            return compiled_interp([x], xp, fp, left, right).item()
+        else:
+            return compiled_interp(x, xp, fp, left, right)
+
+    The source code is only returned for objects written in Python.
+
+    >>> np.source(np.array)
+    Not available for this object.
+
     """
     # Local import to speed up numpy's import time.
     import inspect
@@ -544,28 +627,41 @@ def lookfor(what, module=None, import_modules=True, regenerate=False):
     Do a keyword search on docstrings.
 
     A list of of objects that matched the search is displayed,
-    sorted by relevance.
+    sorted by relevance. All given keywords need to be found in the
+    docstring for it to be returned as a result, but the order does
+    not matter.
 
     Parameters
     ----------
     what : str
         String containing words to look for.
-    module : str, module
-        Module whose docstrings to go through.
-    import_modules : bool
+    module : str, optional
+        Name of module whose docstrings to go through.
+    import_modules : bool, optional
         Whether to import sub-modules in packages.
-        Will import only modules in ``__all__``.
-    regenerate : bool
-        Whether to re-generate the docstring cache.
+        Will import only modules in ``__all__``. Default is True.
+    regenerate : bool, optional
+        Whether to re-generate the docstring cache. Default is False.
 
-    Examples
+    See Also
     --------
+    source, info
+
+    Notes
+    -----
+    Relevance is determined only roughly, by checking if the keywords occur
+    in the function name, at the start of a docstring, etc.
 
+    Examples
+    --------
     >>> np.lookfor('binary representation')
     Search results for 'binary representation'
     ------------------------------------------
     numpy.binary_repr
         Return the binary representation of the input number as a string.
+    numpy.base_repr
+        Return a string representation of a number in the given base system.
+    ...
 
     """
     import pydoc