DOC: Added depr note to swapaxes docstrings (#54125)

* Added depr note to swapaxes docstrings

* Corrected note

Author: DeaMariaLeon

ci/code_checks.sh

@@ -149,7 +149,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         pandas.api.extensions.ExtensionArray.shape \
         pandas.api.extensions.ExtensionArray.tolist \
         pandas.DataFrame.pad \
-        pandas.DataFrame.swapaxes \
         pandas.DataFrame.plot \
         pandas.DataFrame.to_gbq \
         pandas.DataFrame.__dataframe__

pandas/core/generic.py

@@ -771,9 +771,17 @@ def swapaxes(self, axis1: Axis, axis2: Axis, copy: bool_t | None = None) -> Self
         """
         Interchange axes and swap values axes appropriately.
 
+        .. deprecated:: 2.1.0
+            ``swapaxes`` is deprecated and will be removed.
+            Please use ``transpose`` instead.
+
         Returns
         -------
         same as input
+
+        Examples
+        --------
+        Please see examples for :meth:`DataFrame.transpose`.
         """
         warnings.warn(
             # GH#51946