DOC: Updates Index.reindex docstrings (#40328)

pandas/core/indexes/base.py

@@ -3763,18 +3763,59 @@ def _validate_can_reindex(self, indexer: np.ndarray) -> None:
 
     def reindex(self, target, method=None, level=None, limit=None, tolerance=None):
         """
-        Create index with target's values.
+        Create an index with target's values.
 
         Parameters
         ----------
         target : an iterable
+        method : {None, ‘backfill’/’bfill’, ‘pad’/’ffill’, ‘nearest’}
+            Method to use for filling holes in reindexed DataFrame.
+            Please note: this is only applicable to DataFrames/Series
+            with a monotonically increasing/decreasing index.
+            - None (default): don’t fill gaps
+            - pad / ffill: Propagate last valid observation forward to next valid.
+            - backfill / bfill: Use next valid observation to fill gap.
+            - nearest: Use nearest valid observations to fill gap.
+        level : int or name
+            Broadcast across a level, matching Index values on
+            the passed MultiIndex level.
+        limit : int, default None
+            Maximum number of consecutive elements to forward or backward fill.
+        tolerance : optional
+            Maximum distance between original and new labels for inexact matches.
+            The values of the index at the matching locations most satisfy the
+            equation `abs(index[indexer] - target) <= tolerance`.
+            Tolerance may be a scalar value, which applies the same tolerance
+            to all values, or list-like, which applies variable tolerance per element.
+            List-like includes list, tuple, array, Series, and must be the same size
+            as the index and its dtype must exactly match the index’s type.
 
         Returns
         -------
         new_index : pd.Index
             Resulting index.
         indexer : np.ndarray or None
             Indices of output values in original index.
+
+        Examples
+        --------
+        >>> index = ['a', 'b', 'c', 'd']
+        >>> df = pd.DataFrame({"A": [1,2,3,4],
+        ...                   "B": [5,6,7,8],
+        ...                   "C": [9,10,11,12]},
+        ...                   index=index)
+        >>> df
+            A   B   C
+        a   1   5   9
+        b   2   6   10
+        c   3   7   11
+        d   4   8   12
+        >>> target, indexer = df.index.reindex(target=['I', 'II', 'III', 'IV'])
+        >>> target, indexer
+        (Index(['I', 'II', 'III', 'IV'], dtype='object'), array([-1, -1, -1, -1]))
+        >>> target, indexer = df.index.reindex(target=['I', 'd', 'a', 'IV'])
+        >>> target, indexer
+        (Index(['I', 'd', 'III', 'IV'], dtype='object'), array([-1,  3, 0, -1]))
         """
         # GH6552: preserve names when reindexing to non-named target
         # (i.e. neither Index nor Series).