DOC: update the Series.isin docstring

pandas/core/series.py

@@ -2745,20 +2745,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
  -------
@@ -2767,31 +2768,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)