From d8181a5b5bdee57bc458f103862d83687be95641 Mon Sep 17 00:00:00 2001
From: DaanVanHauwermeiren <DaanVanHauwermeiren@users.noreply.github.com>
Date: Sat, 10 Mar 2018 17:25:20 +0100
Subject: [PATCH] DOC: update the Series.isin docstring (#20175)

---
 pandas/core/series.py | 39 +++++++++++++++++++++++----------------
 1 file changed, 23 insertions(+), 16 deletions(-)

diff --git a/pandas/core/series.py b/pandas/core/series.py
index 090f599c860ae..0d1145961e79e 100644
--- a/pandas/core/series.py
+++ b/pandas/core/series.py
@@ -2814,20 +2814,21 @@ def _take(self, indices, axis=0, convert=True, is_copy=False):
 
     def isin(self, values):
         """
-        Return a boolean :class:`~pandas.Series` showing whether each element
-        in the :class:`~pandas.Series` is exactly contained in the passed
-        sequence of ``values``.
+        Check whether `values` are contained in Series.
+
+        Return a boolean Series showing whether each element in the Series
+        matches an element in the passed sequence of `values` exactly.
 
         Parameters
         ----------
         values : set or list-like
             The sequence of values to test. Passing in a single string will
             raise a ``TypeError``. Instead, turn a single string into a
-            ``list`` of one element.
+            list of one element.
 
             .. versionadded:: 0.18.1
 
-            Support for values as a set
+              Support for values as a set.
 
         Returns
         -------
@@ -2836,31 +2837,37 @@ def isin(self, values):
         Raises
         ------
         TypeError
-          * If ``values`` is a string
+          * If `values` is a string
 
         See Also
         --------
-        pandas.DataFrame.isin
+        pandas.DataFrame.isin : equivalent method on DataFrame
 
         Examples
         --------
 
-        >>> s = pd.Series(list('abc'))
-        >>> s.isin(['a', 'c', 'e'])
+        >>> s = pd.Series(['lama', 'cow', 'lama', 'beetle', 'lama',
+        ...                'hippo'], name='animal')
+        >>> s.isin(['cow', 'lama'])
         0     True
-        1    False
+        1     True
         2     True
-        dtype: bool
+        3    False
+        4     True
+        5    False
+        Name: animal, dtype: bool
 
-        Passing a single string as ``s.isin('a')`` will raise an error. Use
+        Passing a single string as ``s.isin('lama')`` will raise an error. Use
         a list of one element instead:
 
-        >>> s.isin(['a'])
+        >>> s.isin(['lama'])
         0     True
         1    False
-        2    False
-        dtype: bool
-
+        2     True
+        3    False
+        4     True
+        5    False
+        Name: animal, dtype: bool
         """
         result = algorithms.isin(com._values_from_object(self), values)
         return self._constructor(result, index=self.index).__finalize__(self)