DOC: Harmonize max and min docstrings with each other

3 files changed, 40 insertions, 38 deletions

diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py
index 8c6884003..53ccfcfda 100644
--- a/numpy/core/code_generators/ufunc_docstrings.py
+++ b/numpy/core/code_generators/ufunc_docstrings.py
@@ -2170,14 +2170,12 @@ add_newdoc('numpy.core.umath', 'maximum',
     """
     Element-wise maximum of array elements.
 
-    Compare two arrays and returns a new array containing
-    the element-wise maxima. If one of the elements being
-    compared is a nan, then that element is returned. If
-    both elements are nans then the first is returned. The
-    latter distinction is important for complex nans,
-    which are defined as at least one of the real or
-    imaginary parts being a nan. The net effect is that
-    nans are propagated.
+    Compare two arrays and returns a new array containing the element-wise
+    maxima. If one of the elements being compared is a nan, then that element
+    is returned. If both elements are nans then the first is returned. The
+    latter distinction is important for complex nans, which are defined as at
+    least one of the real or imaginary parts being a nan. The net effect is
+    that nans are propagated.
 
     Parameters
     ----------
@@ -2206,15 +2204,15 @@ add_newdoc('numpy.core.umath', 'maximum',
 
     Notes
     -----
-    Equivalent to ``np.where(x1 > x2, x1, x2)`` but faster and does proper
-    broadcasting.
+    The maximum is equivalent to ``np.where(x1 >= x2, x1, x2)`` when neither
+    x1 nor x2 are nans, but it is faster and does proper broadcasting.
 
     Examples
     --------
     >>> np.maximum([2, 3, 4], [1, 5, 2])
     array([2, 5, 4])
 
-    >>> np.maximum(np.eye(2), [0.5, 2])
+    >>> np.maximum(np.eye(2), [0.5, 2]) # broadcasting
     array([[ 1. ,  2. ],
            [ 0.5,  2. ]])
 
@@ -2277,6 +2275,8 @@ add_newdoc('numpy.core.umath', 'minimum',
 
     >>> np.minimum([np.nan, 0, np.nan],[0, np.nan, np.nan])
     array([ NaN,  NaN,  NaN])
+    >>> np.minimum(-np.Inf, 1)
+    -inf
 
     """)
 
@@ -2339,8 +2339,6 @@ add_newdoc('numpy.core.umath', 'fmax',
 
 add_newdoc('numpy.core.umath', 'fmin',
     """
-    fmin(x1, x2[, out])
-
     Element-wise minimum of array elements.
 
     Compare two arrays and returns a new array containing the element-wise
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index bf92d6539..5735b6124 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -1903,11 +1903,11 @@ def amax(a, axis=None, out=None, keepdims=False):
     a : array_like
         Input data.
     axis : int, optional
-        Axis along which to operate.  By default flattened input is used.
+        Axis along which to operate.  By default, flattened input is used.
     out : ndarray, optional
-        Alternate output array in which to place the result.  Must be of
-        the same shape and buffer length as the expected output.  See
-        `doc.ufuncs` (Section "Output arguments") for more details.
+        Alternative output array in which to place the result.  Must
+        be of the same shape and buffer length as the expected output.
+        See `doc.ufuncs` (Section "Output arguments") for more details.
     keepdims : bool, optional
         If this is set to True, the axes which are reduced are left
         in the result as dimensions with size one. With this option,
@@ -1938,7 +1938,7 @@ def amax(a, axis=None, out=None, keepdims=False):
     Notes
     -----
     NaN values are propagated, that is if at least one item is NaN, the
-    corresponding max value will be NaN as well.  To ignore NaN values
+    corresponding max value will be NaN as well. To ignore NaN values
     (MATLAB behavior), please use nanmax.
     
     Don't use `amax` for element-wise comparison of 2 arrays; when
@@ -1951,11 +1951,11 @@ def amax(a, axis=None, out=None, keepdims=False):
     >>> a
     array([[0, 1],
            [2, 3]])
-    >>> np.amax(a)
+    >>> np.amax(a)           # Maximum of the flattened array
     3
-    >>> np.amax(a, axis=0)
+    >>> np.amax(a, axis=0)   # Maxima along the first axis
     array([2, 3])
-    >>> np.amax(a, axis=1)
+    >>> np.amax(a, axis=1)   # Maxima along the second axis
     array([1, 3])
 
     >>> b = np.arange(5, dtype=np.float)
@@ -1972,7 +1972,7 @@ def amax(a, axis=None, out=None, keepdims=False):
         except AttributeError:
             return _methods._amax(a, axis=axis,
                                 out=out, keepdims=keepdims)
-        # NOTE: Dropping and keepdims parameter
+        # NOTE: Dropping the keepdims parameter
         return amax(axis=axis, out=out)
     else:
         return _methods._amax(a, axis=axis,
@@ -1987,7 +1987,7 @@ def amin(a, axis=None, out=None, keepdims=False):
     a : array_like
         Input data.
     axis : int, optional
-        Axis along which to operate.  By default a flattened input is used.
+        Axis along which to operate.  By default, flattened input is used.
     out : ndarray, optional
         Alternative output array in which to place the result.  Must
         be of the same shape and buffer length as the expected output.
@@ -1999,8 +1999,10 @@ def amin(a, axis=None, out=None, keepdims=False):
 
     Returns
     -------
-    amin : ndarray
-        A new array or a scalar array with the result.
+    amin : ndarray or scalar
+        Minimum of `a`. If `axis` is None, the result is a scalar value.
+        If `axis` is given, the result is an array of dimension
+        ``a.ndim - 1``.
 
     See Also
     --------
@@ -2019,9 +2021,9 @@ def amin(a, axis=None, out=None, keepdims=False):
 
     Notes
     -----
-    NaN values are propagated, that is if at least one item is nan, the
-    corresponding min value will be nan as well. To ignore NaN values (matlab
-    behavior), please use nanmin.
+    NaN values are propagated, that is if at least one item is NaN, the
+    corresponding min value will be NaN as well. To ignore NaN values
+    (MATLAB behavior), please use nanmin.
     
     Don't use `amin` for element-wise comparison of 2 arrays; when 
     ``a.shape[0]`` is 2, ``minimum(a[0], a[1])`` is faster than 
@@ -2035,9 +2037,9 @@ def amin(a, axis=None, out=None, keepdims=False):
            [2, 3]])
     >>> np.amin(a)           # Minimum of the flattened array
     0
-    >>> np.amin(a, axis=0)         # Minima along the first axis
+    >>> np.amin(a, axis=0)   # Minima along the first axis
     array([0, 1])
-    >>> np.amin(a, axis=1)         # Minima along the second axis
+    >>> np.amin(a, axis=1)   # Minima along the second axis
     array([0, 2])
 
     >>> b = np.arange(5, dtype=np.float)
diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index 9f3b2a0f8..d782f454a 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -1478,20 +1478,23 @@ def nansum(a, axis=None):
 
 def nanmin(a, axis=None):
     """
-    Return the minimum of an array or minimum along an 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 minimum is desired.
+        Array containing numbers whose minimum is desired. If `a` is not
+        an array, a conversion is attempted.
     axis : int, optional
-        Axis along which the minimum is computed.The default is to compute
+        Axis along which the minimum is computed. The default is to compute
         the minimum of the flattened array.
 
     Returns
     -------
     nanmin : ndarray
-        A new array or a scalar array with the result.
+        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, an ndarray scalar is
+        returned.  The same dtype as `a` is returned.
 
     See Also
     --------
@@ -1519,7 +1522,6 @@ def nanmin(a, axis=None):
 
     If the input has a integer type the function is equivalent to np.min.
 
-
     Examples
     --------
     >>> a = np.array([[1, 2], [3, np.nan]])
@@ -1581,7 +1583,7 @@ def nanargmin(a, axis=None):
 
 def nanmax(a, axis=None):
     """
-    Return the maximum of an array or maximum along an axis ignoring any NaNs.
+    Return the maximum of an array or maximum along an axis, ignoring any NaNs.
 
     Parameters
     ----------
@@ -1596,8 +1598,8 @@ def nanmax(a, axis=None):
     -------
     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 ndarray scalar is
-        returned.  The the same dtype as `a` is returned.
+        If `a` is a 0-d array, or if axis is None, an ndarray scalar is
+        returned.  The same dtype as `a` is returned.
 
     See Also
     --------