DOC: Add deprecation marks to deprecated functions (#48183)

* DOC: Add deprecation marks to deprecated functions

* Address docs

* docstrings

Author: phofl

pandas/_libs/tslibs/timedeltas.pyx

@@ -1054,6 +1054,12 @@ cdef class _Timedelta(timedelta):
 
     @property
     def freq(self) -> None:
+        """
+        Freq property.
+
+        .. deprecated:: 1.5.0
+            This argument is deprecated.
+        """
         # GH#46430
         warnings.warn(
             "Timedelta.freq is deprecated and will be removed in a future version",
@@ -1064,6 +1070,12 @@ cdef class _Timedelta(timedelta):
 
     @property
     def is_populated(self) -> bool:
+        """
+        Is_populated property.
+
+        .. deprecated:: 1.5.0
+            This argument is deprecated.
+        """
         # GH#46430
         warnings.warn(
             "Timedelta.is_populated is deprecated and will be removed in a future version",
@@ -1245,6 +1257,9 @@ cdef class _Timedelta(timedelta):
         """
         Return the timedelta in nanoseconds (ns), for internal compatibility.
 
+        .. deprecated:: 1.5.0
+            This argument is deprecated.
+
         Returns
         -------
         int

pandas/core/base.py

@@ -1057,6 +1057,10 @@ def is_monotonic(self) -> bool:
         """
         Return boolean if values in the object are monotonically increasing.
 
+        .. deprecated:: 1.5.0
+            is_monotonic is deprecated and will be removed in a future version.
+            Use is_monotonic_increasing instead.
+
         Returns
         -------
         bool

pandas/core/frame.py

@@ -1324,7 +1324,35 @@ def items(self) -> Iterable[tuple[Hashable, Series]]:
             for i, k in enumerate(self.columns):
                 yield k, self._ixs(i, axis=1)
 
-    @Appender(_shared_docs["items"])
+    _shared_docs[
+        "iteritems"
+    ] = r"""
+        Iterate over (column name, Series) pairs.
+
+        .. deprecated:: 1.5.0
+            iteritems is deprecated and will be removed in a future version.
+            Use .items instead.
+
+        Iterates over the DataFrame columns, returning a tuple with
+        the column name and the content as a Series.
+
+        Yields
+        ------
+        label : object
+            The column names for the DataFrame being iterated over.
+        content : Series
+            The column entries belonging to each label, as a Series.
+
+        See Also
+        --------
+        DataFrame.iter : Recommended alternative.
+        DataFrame.iterrows : Iterate over DataFrame rows as
+            (index, Series) pairs.
+        DataFrame.itertuples : Iterate over DataFrame rows as namedtuples
+            of the values.
+        """
+
+    @Appender(_shared_docs["iteritems"])
     def iteritems(self) -> Iterable[tuple[Hashable, Series]]:
         warnings.warn(
             "iteritems is deprecated and will be removed in a future version. "

pandas/core/indexes/base.py

@@ -2285,6 +2285,10 @@ def _can_hold_na(self) -> bool:
     def is_monotonic(self) -> bool:
         """
         Alias for is_monotonic_increasing.
+
+        .. deprecated:: 1.5.0
+            is_monotonic is deprecated and will be removed in a future version.
+            Use is_monotonic_increasing instead.
         """
         warnings.warn(
             "is_monotonic is deprecated and will be removed in a future version. "

pandas/core/series.py

@@ -1816,8 +1816,29 @@ def items(self) -> Iterable[tuple[Hashable, Any]]:
         """
         return zip(iter(self.index), iter(self))
 
-    @Appender(items.__doc__)
     def iteritems(self) -> Iterable[tuple[Hashable, Any]]:
+        """
+        Lazily iterate over (index, value) tuples.
+
+        .. deprecated:: 1.5.0
+            iteritems is deprecated and will be removed in a future version.
+            Use .items instead.
+
+        This method returns an iterable tuple (index, value). This is
+        convenient if you want to create a lazy iterator.
+
+        Returns
+        -------
+        iterable
+            Iterable of tuples containing the (index, value) pairs from a
+            Series.
+
+        See Also
+        --------
+        Series.items : Recommended alternative.
+        DataFrame.items : Iterate over (column name, Series) pairs.
+        DataFrame.iterrows : Iterate over DataFrame rows as (index, Series) pairs.
+        """
         warnings.warn(
             "iteritems is deprecated and will be removed in a future version. "
             "Use .items instead.",