more docstring updates from pydoc website (thanks to everyone who contributed!)

4 files changed, 71 insertions, 55 deletions

diff --git a/numpy/lib/financial.py b/numpy/lib/financial.py
index 7f62a81f9..8b77eb3fc 100644
--- a/numpy/lib/financial.py
+++ b/numpy/lib/financial.py
@@ -206,7 +206,7 @@ def pmt(rate, nper, pv, fv=0, when='end'):
 
 def nper(rate, pmt, pv, fv=0, when='end'):
     """
-    Compute the number of periods.
+    Compute the number of periodic payments.
 
     Parameters
     ----------
@@ -225,16 +225,16 @@ def nper(rate, pmt, pv, fv=0, when='end'):
     -----
     The number of periods ``nper`` is computed by solving the equation::
 
-      fv + pv*(1+rate)**nper + pmt*(1+rate*when)/rate * ((1+rate)**nper - 1) == 0
+     fv + pv*(1+rate)**nper + pmt*(1+rate*when)/rate*((1+rate)**nper-1) = 0
 
-    or, when ``rate == 0``::
+    but if ``rate = 0`` then::
 
-      fv + pv + pmt * nper == 0
+     fv + pv + pmt*nper = 0
 
     Examples
     --------
-    If you only had $150 to spend as payment, how long would it take to pay-off
-    a loan of $8,000 at 7% annual interest?
+    If you only had $150/month to pay towards the loan, how long would it take
+    to pay-off a loan of $8,000 at 7% annual interest?
 
     >>> np.nper(0.07/12, -150, 8000)
     64.073348770661852
@@ -244,11 +244,13 @@ def nper(rate, pmt, pv, fv=0, when='end'):
     The same analysis could be done with several different interest rates
     and/or payments and/or total amounts to produce an entire table.
 
-    >>> 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]],
-           [[ 33.07413144,  39.26244268],
-            [ 74.06368256,  90.22989997]]])
+    >>> np.nper(*(np.ogrid[0.07/12: 0.08/12: 0.01/12,
+    ...                    -150   : -99     : 50    ,
+    ...                    8000   : 9001    : 1000]))
+    array([[[  64.07334877,   74.06368256],
+            [ 108.07548412,  127.99022654]],
+           [[  66.12443902,   76.87897353],
+            [ 114.70165583,  137.90124779]]])
 
     """
     when = _convert_when(when)
diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index 92fcf5378..a1f7102df 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -1366,24 +1366,20 @@ def nansum(a, axis=None):
 
 def nanmin(a, axis=None):
     """
-    Return the minimum of array elements over the given axis ignoring any NaNs.
+    Return the minimum of an array or minimum along an axis ignoring any NaNs.
 
     Parameters
     ----------
     a : array_like
-        Array containing numbers whose sum is desired. If `a` is not
-        an array, a conversion is attempted.
+        Array containing numbers whose minimum is desired.
     axis : int, optional
         Axis along which the minimum is computed.The default is to compute
         the minimum of the flattened array.
 
     Returns
     -------
-    y : {ndarray, scalar}
-        An array with the same shape as `a`, with the specified axis removed.
-        If `a` is a 0-d array, or if axis is None, a scalar is returned. The
-        the same dtype as `a` is returned.
-
+    nanmin : ndarray
+        A new array or a scalar array with the result.
 
     See Also
     --------
@@ -1461,7 +1457,7 @@ def nanargmin(a, axis=None):
 
 def nanmax(a, axis=None):
     """
-    Return the maximum of array elements over the given axis ignoring any NaNs.
+    Return the maximum of an array or maximum along an axis ignoring any NaNs.
 
     Parameters
     ----------
@@ -1469,15 +1465,15 @@ def nanmax(a, axis=None):
         Array containing numbers whose maximum is desired. If `a` is not
         an array, a conversion is attempted.
     axis : int, optional
-        Axis along which the maximum is computed.The default is to compute
+        Axis along which the maximum is computed. The default is to compute
         the maximum of the flattened array.
 
     Returns
     -------
-    y : ndarray
+    nanmax : ndarray
         An array with the same shape as `a`, with the specified axis removed.
-        If `a` is a 0-d array, or if axis is None, a scalar is returned. The
-        the same dtype as `a` is returned.
+        If `a` is a 0-d array, or if axis is None, a ndarray scalar is
+        returned.  The the same dtype as `a` is returned.
 
     See Also
     --------
diff --git a/numpy/lib/io.py b/numpy/lib/io.py
index e0b83d89b..ec3f39cc2 100644
--- a/numpy/lib/io.py
+++ b/numpy/lib/io.py
@@ -306,9 +306,11 @@ def save(file, arr):
 
     Parameters
     ----------
-    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.
+    file : file or str
+        File or filename to which the data is saved.  If file is a file-object,
+        then the filename is unchanged.  If file is a string, a ``.npy``
+        extension will be appended to the file name if it does not already
+        have one.
     arr : array_like
         Array data to be saved.
 
@@ -329,7 +331,7 @@ def save(file, arr):
     >>> x = np.arange(10)
     >>> np.save(outfile, x)
 
-    >>> outfile.seek(0) # only necessary in this example (with tempfile)
+    >>> outfile.seek(0) # Only needed here to simulate closing & reopening file
     >>> np.load(outfile)
     array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
 
@@ -348,25 +350,29 @@ def savez(file, *args, **kwds):
     """
     Save several arrays into a single, compressed file in ``.npz`` format.
 
-    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.
+    names, in the .npz file, are 'arr_0', 'arr_1', etc. If keyword arguments
+    are given, the corresponding variable names, in the ``.npz`` file will
+    match the keyword names.
 
     Parameters
     ----------
     file : str or file
         Either the file name (string) or an open file (file-like object)
-        If file is a string, it names the output file.  ".npz" will be appended
-        to the file name if it is not already there.
-    args : 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
-        `savez`, they will be saved with names "arr_0", "arr_1", and so on.
-        These arguments can be any expression.
-    kwds : Keyword arguments
-        All keyword=value pairs cause the value to be saved with the name of
-        the keyword.
+        where the data will be saved. If file is a string, the ``.npz``
+        extension will be appended to the file name if it is not already there.
+    \\*args : Arguments, optional
+        Arrays to save to the file. Since it is not possible for Python to
+        know the names of the arrays outside `savez`, the arrays will be saved
+        with names "arr_0", "arr_1", and so on. These arguments can be any
+        expression.
+    \\*\\*kwds : Keyword arguments, optional
+        Arrays to save to the file. Arrays will be saved in the file with the
+        keyword names.
+
+    Returns
+    -------
+    None
 
     See Also
     --------
@@ -379,6 +385,11 @@ def savez(file, *args, **kwds):
     variables they contain.  Each file contains one variable in ``.npy``
     format. For a description of the ``.npy`` format, see `format`.
 
+    When opening the saved ``.npz`` file with `load` a `NpzFile` object is
+    returned. This is a dictionary-like object which can be queried for
+    its list of arrays (with the ``.files`` attribute), and for the arrays
+    themselves.
+
     Examples
     --------
     >>> from tempfile import TemporaryFile
@@ -389,11 +400,11 @@ def savez(file, *args, **kwds):
     Using `savez` with \\*args, the arrays are saved with default names.
 
     >>> np.savez(outfile, x, y)
-    >>> outfile.seek(0)  # only necessary in this example (with tempfile)
-    >>> npz = np.load(outfile)
-    >>> npz.files
+    >>> outfile.seek(0) # Only needed here to simulate closing & reopening file
+    >>> npzfile = np.load(outfile)
+    >>> npzfile.files
     ['arr_1', 'arr_0']
-    >>> npz['arr_0']
+    >>> npzfile['arr_0']
     array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
 
     Using `savez` with \\*\\*kwds, the arrays are saved with the keyword names.
@@ -401,10 +412,10 @@ def savez(file, *args, **kwds):
     >>> outfile = TemporaryFile()
     >>> np.savez(outfile, x=x, y=y)
     >>> outfile.seek(0)
-    >>> npz = np.load(outfile)
-    >>> npz.files
+    >>> npzfile = np.load(outfile)
+    >>> npzfile.files
     ['y', 'x']
-    >>> npz['x']
+    >>> npzfile['x']
     array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
 
     """
@@ -510,8 +521,15 @@ def loadtxt(fname, dtype=float, comments='#', delimiter=None, converters=None,
     See Also
     --------
     load, fromstring, fromregex
+    genfromtxt : Load data with missing values handled as specified.
     scipy.io.loadmat : reads Matlab(R) data files
 
+    Notes
+    -----
+    This function aims to be a fast reader for simply formatted files. The
+    `genfromtxt` function provides more sophisticated handling of, e.g.,
+    lines with missing values.
+
     Examples
     --------
     >>> from StringIO import StringIO   # StringIO behaves like a file object
diff --git a/numpy/lib/shape_base.py b/numpy/lib/shape_base.py
index 69fe98314..ff187c63b 100644
--- a/numpy/lib/shape_base.py
+++ b/numpy/lib/shape_base.py
@@ -301,7 +301,7 @@ def dstack(tup):
     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``.
+    to make a single array. Rebuilds arrays divided by `dsplit`.
     This is a simple way to stack 2D arrays (images) into a single
     3D array for processing.
 
@@ -325,7 +325,7 @@ def dstack(tup):
 
     Notes
     -----
-    Equivalent to ``np.concatenate(tup, axis=2)``
+    Equivalent to ``np.concatenate(tup, axis=2)``.
 
     Examples
     --------
@@ -420,7 +420,7 @@ def split(ary,indices_or_sections,axis=0):
 
         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
+        ``[2, 3]`` would, for ``axis=0``, result in
 
           - ary[:2]
           - ary[2:3]
@@ -483,8 +483,8 @@ def hsplit(ary,indices_or_sections):
     """
     Split an array into multiple sub-arrays horizontally (column-wise).
 
-    Please refer to the ``split`` documentation.  ``hsplit`` is equivalent
-    to ``split`` with `axis=1`, the array is always split along the second
+    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
@@ -596,8 +596,8 @@ def dsplit(ary,indices_or_sections):
     """
     Split array into multiple sub-arrays along the 3rd axis (depth).
 
-    Please refer to the ``split`` documentation.  ``dsplit`` is equivalent
-    to ``split`` with `axis=2`, the array is always split along the third
+    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