Merge from documentation editor.

1 files changed, 73 insertions, 42 deletions

diff --git a/numpy/lib/arraysetops.py b/numpy/lib/arraysetops.py
index 8fec23cd3..8bd76d17f 100644
--- a/numpy/lib/arraysetops.py
+++ b/numpy/lib/arraysetops.py
@@ -39,8 +39,8 @@ import time
 import numpy as np
 
 def ediff1d(ary, to_end=None, to_begin=None):
-    """The differences between consecutive elements of an array, possibly with
-    prefixed and/or appended values.
+    """
+    The differences between consecutive elements of an array.
 
     Parameters
     ----------
@@ -75,31 +75,38 @@ def ediff1d(ary, to_end=None, to_begin=None):
     return ed
 
 def unique1d(ar1, return_index=False):
-    """Find the unique elements of 1D array.
-
-    Most of the other array set operations operate on the unique arrays
-    generated by this function.
+    """
+    Find the unique elements of an array.
 
     Parameters
     ----------
-    ar1 : array
-        This array will be flattened if it is not already 1D.
+    ar1 : array-like
+        This array will be flattened if it is not already 1-D.
     return_index : bool, optional
-        If True, also return the indices against ar1 that result in the unique
-        array.
+        If True, also return the indices against `ar1` that result in the
+        unique array.
 
     Returns
     -------
-    unique : array
+    unique : ndarray
         The unique values.
-    unique_indices : int array, optional
-        The indices of the unique values. Only provided if return_index is True.
+    unique_indices : ndarray, optional
+        The indices of the unique values. Only provided if `return_index` is
+        True.
 
     See Also
     --------
       numpy.lib.arraysetops : Module with a number of other functions
                               for performing set operations on arrays.
 
+    Examples
+    --------
+    >>> np.unique1d([1, 1, 2, 2, 3, 3])
+    array([1, 2, 3])
+    >>> a = np.array([[1, 1], [2, 3]])
+    >>> np.unique1d(a)
+    array([1, 2, 3])
+
     """
     ar = np.asarray(ar1).flatten()
     if ar.size == 0:
@@ -118,50 +125,60 @@ def unique1d(ar1, return_index=False):
         return ar[flag]
 
 def intersect1d(ar1, ar2):
-    """Intersection of 1D arrays with unique elements.
-
-    Use unique1d() to generate arrays with only unique elements to use as inputs
-    to this function. Alternatively, use intersect1d_nu() which will find the
-    unique values for you.
+    """
+    Intersection returning repeated or unique elements common to both arrays.
 
     Parameters
     ----------
-    ar1 : array
-    ar2 : array
+    ar1,ar2 : array_like
+        Input arrays.
 
     Returns
     -------
-    intersection : array
+    out : ndarray, shape(N,)
+        Sorted 1D array of common elements with repeating elements.
 
     See Also
     --------
+    intersect1d_nu : Returns only unique common 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])
+
     """
     aux = np.concatenate((ar1,ar2))
     aux.sort()
     return aux[aux[1:] == aux[:-1]]
 
 def intersect1d_nu(ar1, ar2):
-    """Intersection of 1D arrays with any elements.
-
-    The input arrays do not have unique elements like intersect1d() requires.
+    """
+    Intersection returning unique elements common to both arrays.
 
     Parameters
     ----------
-    ar1 : array
-    ar2 : array
+    ar1,ar2 : array_like
+        Input arrays.
 
     Returns
     -------
-    intersection : array
+    out : ndarray, shape(N,)
+        Sorted 1D array of common and unique elements.
 
     See Also
     --------
+    intersect1d : Returns repeated or unique common 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])
+    array([1, 3])
+
     """
     # Might be faster than unique1d( intersect1d( ar1, ar2 ) )?
     aux = np.concatenate((unique1d(ar1), unique1d(ar2)))
@@ -169,15 +186,18 @@ def intersect1d_nu(ar1, ar2):
     return aux[aux[1:] == aux[:-1]]
 
 def setxor1d(ar1, ar2):
-    """Set exclusive-or of 1D arrays with unique elements.
+    """
+    Set exclusive-or of 1D arrays with unique elements.
 
-    Use unique1d() to generate arrays with only unique elements to use as inputs
-    to this function.
+    Use unique1d() to generate arrays with only unique elements to use as
+    inputs to this function.
 
     Parameters
     ----------
     ar1 : array
+        Input array.
     ar2 : array
+        Input array.
 
     Returns
     -------
@@ -202,20 +222,25 @@ def setxor1d(ar1, ar2):
     return aux[flag2]
 
 def setmember1d(ar1, ar2):
-    """Return a boolean array of shape of ar1 containing True where the elements
-    of ar1 are in ar2 and False otherwise.
+    """
+    Return a boolean array set True where first element is in 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.
+    Use unique1d() to generate arrays with only unique elements to use as
+    inputs to this function.
 
     Parameters
     ----------
     ar1 : array
+        Input array.
     ar2 : array
+        Input array.
 
     Returns
     -------
-    mask : bool array
+    mask : bool-array
         The values ar1[mask] are in ar2.
 
     See Also
@@ -252,17 +277,20 @@ def union1d(ar1, ar2):
     """
     Union of 1D arrays with unique elements.
 
-    Use unique1d() to generate arrays with only unique elements to use as inputs
-    to this function.
+    Use unique1d() to generate arrays with only unique elements to use as
+    inputs to this function.
 
     Parameters
     ----------
-    ar1 : array
-    ar2 : array
+    ar1 : array_like, shape(M,)
+        Input array.
+    ar2 : array_like, shape(N,)
+        Input array.
 
     Returns
     -------
     union : array
+        Unique union of input arrays.
 
     See also
     --------
@@ -273,15 +301,18 @@ def union1d(ar1, ar2):
     return unique1d( np.concatenate( (ar1, ar2) ) )
 
 def setdiff1d(ar1, ar2):
-    """Set difference of 1D arrays with unique elements.
+    """
+    Set difference of 1D arrays with unique elements.
 
-    Use unique1d() to generate arrays with only unique elements to use as inputs
-    to this function.
+    Use unique1d() to generate arrays with only unique elements to use as
+    inputs to this function.
 
     Parameters
     ----------
     ar1 : array
+        Input array.
     ar2 : array
+        Input comparison array.
 
     Returns
     -------