DOC: Improve the docstring of pd.Index.contains and closes PR #20211

pandas/core/indexes/base.py

@@ -3812,38 +3812,51 @@ def _is_memory_usage_qualified(self):
     def is_type_compatible(self, kind):
         return kind == self.inferred_type
 
-    _index_shared_docs['__contains__'] = """
-        Return a boolean if this key is IN the index.
+    _index_shared_docs['contains'] = """
+        Return a boolean indicating whether the provided key is in the index.
 
         Parameters
         ----------
-        key : object
+        key : label
+            The key to check if it is present in the index.
 
         Returns
         -------
-        boolean
+        bool
+            Whether the key search is in the index.
+
+        See Also
+        --------
+        Index.isin : Returns an ndarray of boolean dtype indicating whether the
+            list-like key is in the index.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 2, 3, 4])
+        >>> idx
+        Int64Index([1, 2, 3, 4], dtype='int64')
+
+        >>> idx.contains(2)
+        True
+        >>> idx.contains(6)
+        False
+
+        This is equivalent to:
+
+        >>> 2 in idx
+        True
+        >>> 6 in idx
+        False
         """
 
-    @Appender(_index_shared_docs['__contains__'] % _index_doc_kwargs)
+    @Appender(_index_shared_docs['contains'] % _index_doc_kwargs)
     def __contains__(self, key):
         hash(key)
         try:
             return key in self._engine
         except (OverflowError, TypeError, ValueError):
             return False
 
-    _index_shared_docs['contains'] = """
-        Return a boolean if this key is IN the index.
-
-        Parameters
-        ----------
-        key : object
-
-        Returns
-        -------
-        boolean
-        """
-
     @Appender(_index_shared_docs['contains'] % _index_doc_kwargs)
     def contains(self, key):
         hash(key)

pandas/core/indexes/category.py

@@ -359,7 +359,7 @@ def ordered(self):
     def _reverse_indexer(self):
         return self._data._reverse_indexer()
 
-    @Appender(_index_shared_docs['__contains__'] % _index_doc_kwargs)
+    @Appender(_index_shared_docs['contains'] % _index_doc_kwargs)
     def __contains__(self, key):
         # if key is a NaN, check if any NaN is in self.
         if isna(key):

pandas/core/indexes/datetimelike.py

@@ -150,7 +150,7 @@ def _box_values_as_index(self):
         from pandas.core.index import Index
         return Index(self._box_values(self.asi8), name=self.name, dtype=object)
 
-    @Appender(_index_shared_docs['__contains__'] % _index_doc_kwargs)
+    @Appender(_index_shared_docs['contains'] % _index_doc_kwargs)
     def __contains__(self, key):
         try:
             res = self.get_loc(key)

pandas/core/indexes/multi.py

@@ -755,7 +755,7 @@ def _shallow_copy_with_infer(self, values, **kwargs):
                               **kwargs)
         return self._shallow_copy(values, **kwargs)
 
-    @Appender(_index_shared_docs['__contains__'] % _index_doc_kwargs)
+    @Appender(_index_shared_docs['contains'] % _index_doc_kwargs)
     def __contains__(self, key):
         hash(key)
         try:

pandas/core/indexes/period.py

@@ -400,7 +400,7 @@ def _mpl_repr(self):
     def _engine(self):
         return self._engine_type(lambda: self, len(self))
 
-    @Appender(_index_shared_docs['__contains__'])
+    @Appender(_index_shared_docs['contains'])
     def __contains__(self, key):
         if isinstance(key, Period):
             if key.freq != self.freq: