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