DOC: Mention all min/max functions from all others, clarify differences

3 files changed, 91 insertions, 35 deletions

diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py
index 5bb5f3f00..8c6884003 100644
--- a/numpy/core/code_generators/ufunc_docstrings.py
+++ b/numpy/core/code_generators/ufunc_docstrings.py
@@ -2194,13 +2194,15 @@ add_newdoc('numpy.core.umath', 'maximum',
     See Also
     --------
     minimum :
-      element-wise minimum
-
+        Element-wise minimum of two arrays, propagating any NaNs.
     fmax :
-      element-wise maximum that ignores nans unless both inputs are nans.
-
-    fmin :
-      element-wise minimum that ignores nans unless both inputs are nans.
+        Element-wise maximum of two arrays, ignoring any NaNs.
+    amax :
+        The maximum value of an array along a given axis, propagating any NaNs.
+    nanmax :
+        The maximum value of an array along a given axis, ignoring any NaNs.
+    
+    fmin, amin, nanmin
 
     Notes
     -----
@@ -2249,11 +2251,15 @@ add_newdoc('numpy.core.umath', 'minimum',
     See Also
     --------
     maximum :
-      element-wise minimum that propagates nans.
-    fmax :
-      element-wise maximum that ignores nans unless both inputs are nans.
+        Element-wise maximum of two arrays, propagating any NaNs.
     fmin :
-      element-wise minimum that ignores nans unless both inputs are nans.
+        Element-wise minimum of two arrays, ignoring any NaNs.
+    amin :
+        The minimum value of an array along a given axis, propagating any NaNs.
+    nanmin :
+        The minimum value of an array along a given axis, ignoring any NaNs.
+
+    fmax, amax, nanmax
 
     Notes
     -----
@@ -2300,11 +2306,15 @@ add_newdoc('numpy.core.umath', 'fmax',
     See Also
     --------
     fmin :
-      element-wise minimum that ignores nans unless both inputs are nans.
+        Element-wise minimum of two arrays, ignoring any NaNs.
     maximum :
-      element-wise maximum that propagates nans.
-    minimum :
-      element-wise minimum that propagates nans.
+        Element-wise maximum of two arrays, propagating any NaNs.
+    amax :
+        The maximum value of an array along a given axis, propagating any NaNs.
+    nanmax :
+        The maximum value of an array along a given axis, ignoring any NaNs.
+
+    minimum, amin, nanmin
 
     Notes
     -----
@@ -2355,11 +2365,15 @@ add_newdoc('numpy.core.umath', 'fmin',
     See Also
     --------
     fmax :
-      element-wise maximum that ignores nans unless both inputs are nans.
-    maximum :
-      element-wise maximum that propagates nans.
+        Element-wise maximum of two arrays, ignoring any NaNs.
     minimum :
-      element-wise minimum that propagates nans.
+        Element-wise minimum of two arrays, propagating any NaNs.
+    amin :
+        The minimum value of an array along a given axis, propagating any NaNs.
+    nanmin :
+        The minimum value of an array along a given axis, ignoring any NaNs.
+
+    maximum, amax, nanmax
 
     Notes
     -----
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index c34348e22..bf92d6539 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -1922,15 +1922,28 @@ def amax(a, axis=None, out=None, keepdims=False):
 
     See Also
     --------
-    nanmax : NaN values are ignored instead of being propagated.
-    fmax : same behavior as the C99 fmax function.
-    argmax : indices of the maximum values.
+    amin :
+        The minimum value of an array along a given axis, propagating any NaNs.
+    nanmax :
+        The maximum value of an array along a given axis, ignoring any NaNs.
+    maximum :
+        Element-wise maximum of two arrays, propagating any NaNs.
+    fmax :
+        Element-wise maximum of two arrays, ignoring any NaNs.
+    argmax : 
+        Return the indices of the maximum values.
+    
+    nanmin, minimum, fmin
 
     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
     (MATLAB behavior), please use nanmax.
+    
+    Don't use `amax` for element-wise comparison of 2 arrays; when
+    ``a.shape[0]`` is 2, ``maximum(a[0], a[1])`` is faster than 
+    ``amax(a, axis=0)``.
 
     Examples
     --------
@@ -1991,17 +2004,28 @@ def amin(a, axis=None, out=None, keepdims=False):
 
     See Also
     --------
-    nanmin: nan values are ignored instead of being propagated
-    fmin: same behavior as the C99 fmin function
-    argmin: Return the indices of the minimum values.
+    amax :
+        The maximum value of an array along a given axis, propagating any NaNs.
+    nanmin :
+        The minimum value of an array along a given axis, ignoring any NaNs.
+    minimum :
+        Element-wise minimum of two arrays, propagating any NaNs.
+    fmin :
+        Element-wise minimum of two arrays, ignoring any NaNs.
+    argmin : 
+        Return the indices of the minimum values.
 
-    amax, nanmax, fmax
+    nanmax, maximum, fmax
 
     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.
+    
+    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 
+    ``amin(a, axis=0)``.
 
     Examples
     --------
diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index a7163a7ca..9f3b2a0f8 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -1495,11 +1495,20 @@ def nanmin(a, axis=None):
 
     See Also
     --------
-    numpy.amin : Minimum across array including any Not a Numbers.
-    numpy.nanmax : Maximum across array ignoring any Not a Numbers.
-    isnan : Shows which elements are Not a Number (NaN).
-    isfinite: Shows which elements are not: Not a Number, positive and
-             negative infinity
+    nanmax :
+        The maximum value of an array along a given axis, ignoring any NaNs.
+    amin :
+        The minimum value of an array along a given axis, propagating any NaNs.
+    fmin :
+        Element-wise minimum of two arrays, ignoring any NaNs.
+    minimum :
+        Element-wise minimum of two arrays, propagating any NaNs.
+    isnan :
+        Shows which elements are Not a Number (NaN).
+    isfinite:
+        Shows which elements are neither NaN nor infinity.
+        
+    amax, fmax, maximum
 
     Notes
     -----
@@ -1592,11 +1601,20 @@ def nanmax(a, axis=None):
 
     See Also
     --------
-    numpy.amax : Maximum across array including any Not a Numbers.
-    numpy.nanmin : Minimum across array ignoring any Not a Numbers.
-    isnan : Shows which elements are Not a Number (NaN).
-    isfinite: Shows which elements are not: Not a Number, positive and
-             negative infinity
+    nanmin :
+        The minimum value of an array along a given axis, ignoring any NaNs.
+    amax :
+        The maximum value of an array along a given axis, propagating any NaNs.
+    fmax :
+        Element-wise maximum of two arrays, ignoring any NaNs.
+    maximum :
+        Element-wise maximum of two arrays, propagating any NaNs.
+    isnan :
+        Shows which elements are Not a Number (NaN).
+    isfinite:
+        Shows which elements are neither NaN nor infinity.
+        
+    amin, fmin, minimum
 
     Notes
     -----