ENH sync ndarray methods doc/args with numpy function doc/args

Modified the docstrings to all, any, sum, prod, mean, var, std, min, max
to add keepdims argument.

Added 'out' keyword parameter to numpy.argmin, numpy.argmax, to mirror
ndarray methods.

Updated ndarray.clip docstring to give correct parameter description.

4 files changed, 61 insertions, 16 deletions

diff --git a/doc/release/1.10.0-notes.rst b/doc/release/1.10.0-notes.rst
index f6e8c09ef..d5cd99203 100644
--- a/doc/release/1.10.0-notes.rst
+++ b/doc/release/1.10.0-notes.rst
@@ -153,6 +153,12 @@ interpolation behavior.
 NumPy arrays are supported as input for ``pad_width``, and an exception is
 raised if its values are not of integral type.
 
+*np.argmax* and *np.argmin* now support an ``out`` argument
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``out`` parameter was added to *np.argmax* and *np.argmin* for consistency
+with *ndarray.argmax* and *ndarray.argmin*. The new parameter behaves exactly
+as it does in those methods.
+
 More system C99 complex functions detected and used
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 All of the functions ``in complex.h`` are now detected. There are new
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 7dd8c5649..4cc626ca9 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -2982,7 +2982,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('__setstate__',
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('all',
     """
-    a.all(axis=None, out=None)
+    a.all(axis=None, out=None, keepdims=False)
 
     Returns True if all elements evaluate to True.
 
@@ -2997,7 +2997,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('all',
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('any',
     """
-    a.any(axis=None, out=None)
+    a.any(axis=None, out=None, keepdims=False)
 
     Returns True if any of the elements of `a` evaluate to True.
 
@@ -3198,9 +3198,10 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('choose',
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('clip',
     """
-    a.clip(a_min, a_max, out=None)
+    a.clip(min=None, max=None, out=None)
 
-    Return an array whose values are limited to ``[a_min, a_max]``.
+    Return an array whose values are limited to ``[min, max]``.
+    One of max or min must be given.
 
     Refer to `numpy.clip` for full documentation.
 
@@ -3656,7 +3657,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('max',
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('mean',
     """
-    a.mean(axis=None, dtype=None, out=None)
+    a.mean(axis=None, dtype=None, out=None, keepdims=False)
 
     Returns the average of the array elements along given axis.
 
@@ -3671,7 +3672,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('mean',
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('min',
     """
-    a.min(axis=None, out=None)
+    a.min(axis=None, out=None, keepdims=False)
 
     Return the minimum along a given axis.
 
@@ -3769,7 +3770,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('nonzero',
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('prod',
     """
-    a.prod(axis=None, dtype=None, out=None)
+    a.prod(axis=None, dtype=None, out=None, keepdims=False)
 
     Return the product of the array elements over the given axis
 
@@ -4300,7 +4301,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('squeeze',
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('std',
     """
-    a.std(axis=None, dtype=None, out=None, ddof=0)
+    a.std(axis=None, dtype=None, out=None, ddof=0, keepdims=False)
 
     Returns the standard deviation of the array elements along given axis.
 
@@ -4315,7 +4316,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('std',
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('sum',
     """
-    a.sum(axis=None, dtype=None, out=None)
+    a.sum(axis=None, dtype=None, out=None, keepdims=False)
 
     Return the sum of the array elements over the given axis.
 
@@ -4547,7 +4548,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('transpose',
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('var',
     """
-    a.var(axis=None, dtype=None, out=None, ddof=0)
+    a.var(axis=None, dtype=None, out=None, ddof=0, keepdims=False)
 
     Returns the variance of the array elements, along given axis.
 
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index b0c141178..549647df2 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -900,7 +900,7 @@ def argsort(a, axis=-1, kind='quicksort', order=None):
     return argsort(axis, kind, order)
 
 
-def argmax(a, axis=None):
+def argmax(a, axis=None, out=None):
     """
     Returns the indices of the maximum values along an axis.
 
@@ -911,6 +911,9 @@ def argmax(a, axis=None):
     axis : int, optional
         By default, the index is into the flattened array, otherwise
         along the specified axis.
+    out : array, optional
+        If provided, the result will be inserted into this array. It should
+        be of the appropriate shape and dtype.
 
     Returns
     -------
@@ -953,11 +956,11 @@ def argmax(a, axis=None):
     try:
         argmax = a.argmax
     except AttributeError:
-        return _wrapit(a, 'argmax', axis)
-    return argmax(axis)
+        return _wrapit(a, 'argmax', axis, out)
+    return argmax(axis, out)
 
 
-def argmin(a, axis=None):
+def argmin(a, axis=None, out=None):
     """
     Returns the indices of the minimum values along an axis.
 
@@ -968,6 +971,9 @@ def argmin(a, axis=None):
     axis : int, optional
         By default, the index is into the flattened array, otherwise
         along the specified axis.
+    out : array, optional
+        If provided, the result will be inserted into this array. It should
+        be of the appropriate shape and dtype.
 
     Returns
     -------
@@ -1010,8 +1016,8 @@ def argmin(a, axis=None):
     try:
         argmin = a.argmin
     except AttributeError:
-        return _wrapit(a, 'argmin', axis)
-    return argmin(axis)
+        return _wrapit(a, 'argmin', axis, out)
+    return argmin(axis, out)
 
 
 def searchsorted(a, v, side='left', sorter=None):
diff --git a/numpy/core/tests/test_multiarray.py b/numpy/core/tests/test_multiarray.py
index 937ca9d72..eab512eea 100644
--- a/numpy/core/tests/test_multiarray.py
+++ b/numpy/core/tests/test_multiarray.py
@@ -2638,6 +2638,22 @@ class TestArgmax(TestCase):
         d[5942] = "as"
         assert_equal(d.argmax(), 5942)
 
+    def test_np_vs_ndarray(self):
+        # make sure both ndarray.argmax and numpy.argmax support out/axis args
+        a = np.random.normal(size=(2,3))
+
+        #check positional args
+        out1 = zeros(2, dtype=int)
+        out2 = zeros(2, dtype=int)
+        assert_equal(a.argmax(1, out1), np.argmax(a, 1, out2))
+        assert_equal(out1, out2)
+
+        #check keyword args
+        out1 = zeros(3, dtype=int)
+        out2 = zeros(3, dtype=int)
+        assert_equal(a.argmax(out=out1, axis=0), np.argmax(a, out=out2, axis=0))
+        assert_equal(out1, out2)
+
 
 class TestArgmin(TestCase):
 
@@ -2748,6 +2764,22 @@ class TestArgmin(TestCase):
         d[6001] = "0"
         assert_equal(d.argmin(), 6001)
 
+    def test_np_vs_ndarray(self):
+        # make sure both ndarray.argmin and numpy.argmin support out/axis args
+        a = np.random.normal(size=(2,3))
+
+        #check positional args
+        out1 = zeros(2, dtype=int)
+        out2 = ones(2, dtype=int)
+        assert_equal(a.argmin(1, out1), np.argmin(a, 1, out2))
+        assert_equal(out1, out2)
+
+        #check keyword args
+        out1 = zeros(3, dtype=int)
+        out2 = ones(3, dtype=int)
+        assert_equal(a.argmin(out=out1, axis=0), np.argmin(a, out=out2, axis=0))
+        assert_equal(out1, out2)
+
 
 class TestMinMax(TestCase):
     def test_scalar(self):