DOC: update the pd.Index.asof docstring

pandas/core/indexes/base.py

@@ -2378,12 +2378,53 @@ def identical(self, other):
 
     def asof(self, label):
         """
-        For a sorted index, return the most recent label up to and including
-        the passed label. Return NaN if not found.
+        Return the label from the index, or, if not present, the previous one.
 
-        See also
+        Assuming that the index is sorted, return the passed index label if it
+        is in the index, or return the previous index label if the passed one
+        is not in the index.
+
+        Parameters
+        ----------
+        label : object
+            The label up to which the method returns the latest index label.
+
+        Returns
+        -------
+        object : The passed label if it is in the index. The previous label
+            if the passed label is not in the sorted index, or NaN if there
+            is no such label.
+
+        See Also
         --------
-        get_loc : asof is a thin wrapper around get_loc with method='pad'
+        Index.get_loc : `asof` is a thin wrapper around `get_loc`
+            with method='pad'.
+
+        Examples
+        --------
+        The method returns the latest index label up to the passed label.
+
+        >>> idx = pd.Index([13, 18, 20])
+        >>> idx.asof(14)
+        13
+
+        If the label is in the index, the method returns the passed label.
+
+        >>> idx.asof(18)
+        18
+
+        If all of the labels in the index are later than the passed label,
+        NaN is returned.
+
+        >>> idx.asof(1)
+        nan
+
+        If the index is not sorted, an error is raised.
+
+        >>> idx_not_sorted = pd.Index([13, 20, 18])
+        >>> idx_not_sorted.asof(18)
+        Traceback (most recent call last):
+        ValueError: index must be monotonic increasing or decreasing
         """
         try:
             loc = self.get_loc(label, method='pad')