DOC: Improve documentation for Index.where

Author: laymonage

pandas/core/indexes/base.py

@@ -3936,37 +3936,35 @@ def memory_usage(self, deep: bool = False) -> int:
 
     def where(self, cond, other=None):
         """
-        Return a copy of self with entries replaced where cond is False.
+        Replace values where the condition is False.
 
         The replacement is taken from other.
 
         Parameters
         ----------
         cond : bool array-like with the same length as self
-            Condition to select the entries on.
+            Condition to select the values on.
         other : scalar, or array-like, default None
             Replacement if the condition is False.
 
         Returns
         -------
         pandas.Index
-            Copy of self with entries replaced from other
+            A copy of self with values replaced from other
             where the condition is False.
 
         See Also
         --------
-        DataFrame.where : Replace values in a DataFrame where the condition is False.
+        Series.where : Same method for Series.
+        DataFrame.where : Same method for DataFrame.
 
         Examples
         --------
-        >>> idx1 = pd.Index([42, 21, 34, 96, 72])
-        >>> idx1
-        Int64Index([42, 21, 34, 96, 72], dtype='int64')
-        >>> idx2 = pd.Index([140, 150, 140, 190, 170])
-        >>> idx2
-        Int64Index([140, 150, 140, 190, 170], dtype='int64')
-        >>> idx1.where((idx2 - 100) > idx1, idx2)
-        Int64Index([140, 21, 34, 190, 170], dtype='int64')
+        >>> idx = pd.Index(['car', 'bike', 'train', 'tractor'])
+        >>> idx
+        Index(['car', 'bike', 'train', 'tractor'], dtype='object')
+        >>> idx.where(idx.isin(['car', 'train']), 'other')
+        Index(['car', 'other', 'train', 'other'], dtype='object')
         """
         if other is None:
             other = self._na_value