matplotlib
diff --git a/‎doc/api/next_api_changes/deprecations/28946-TH.rst
Copy file name to clipboard
+6Lines changed: 6 additions & 0 deletions b/‎doc/api/next_api_changes/deprecations/28946-TH.rst
Copy file name to clipboard
+6Lines changed: 6 additions & 0 deletions
diff --git a/‎lib/matplotlib/pyplot.py
Copy file name to clipboardExpand all lines: lib/matplotlib/pyplot.py
+21-6Lines changed: 21 additions & 6 deletions b/‎lib/matplotlib/pyplot.py
Copy file name to clipboardExpand all lines: lib/matplotlib/pyplot.py
+21-6Lines changed: 21 additions & 6 deletions
@@ -0,0 +1,6 @@
+Calling ``pyplot.polar()`` with an existing non-polar Axes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This currently plots the data into the non-polar Axes, ignoring
+the "polar" intention. This usage scenario is deprecated and
+will raise an error in the future.
@@ -2681,17 +2681,32 @@ def polar(*args, **kwargs) -> list[Line2D]:
 
     call signature::
 
-      polar(theta, r, **kwargs)
-
-    Multiple *theta*, *r* arguments are supported, with format strings, as in
-    `plot`.
+      polar(theta, r, [fmt], **kwargs)
+
+    This is a convenience wrapper around `.pyplot.plot`. It ensures that the
+    current Axes is polar (or creates one if needed) and then passes all parameters
+    to ``.pyplot.plot``.
+
+    .. note::
+        When making polar plots using the :ref:`pyplot API <pyplot_interface>`,
+        ``polar()`` should typically be the first command because that makes sure
+        a polar Axes is created. Using other commands such as ``plt.title()``
+        before this can lead to the implicit creation of a rectangular Axes, in which
+        case a subsequent ``polar()`` call will fail.
     """
     # If an axis already exists, check if it has a polar projection
     if gcf().get_axes():
         ax = gca()
         if not isinstance(ax, PolarAxes):
-            _api.warn_external('Trying to create polar plot on an Axes '
-                               'that does not have a polar projection.')
+            _api.warn_deprecated(
+                "3.10",
+                message="There exists a non-polar current Axes. Therefore, the "
+                        "resulting plot from 'polar()' is non-polar. You likely "
+                        "should call 'polar()' before any other pyplot plotting "
+                        "commands. "
+                        "Support for this scenario is deprecated in %(since)s and "
+                        "will raise an error in %(removal)s"
+            )
     else:
         ax = axes(projection="polar")
     return ax.plot(*args, **kwargs)