MNT: Discourage arrow()

The arrow() design is broken beyond repair. Even though we currently only have to offer `annotate` as a workaround, we should make the limitations more prominent then just a note and we should steer users away.

This is a a step towards deprecation (matplotlib#20387). Unfortunately the discussion of a replacement has stalled (matplotlib#22435) and we have to revive it later. But that shound not hold us from pointing out the flaws
of arrow() more prominently.

Author: timhoffm

lib/matplotlib/axes/_axes.py

@@ -5432,10 +5432,22 @@ def on_changed(collection):
     @_docstring.interpd
     def arrow(self, x, y, dx, dy, **kwargs):
         """
-        Add an arrow to the Axes.
+        [*Discouraged*] Add an arrow to the Axes.
 
         This draws an arrow from ``(x, y)`` to ``(x+dx, y+dy)``.
 
+        .. admonition:: Discouraged
+
+            The use of this method is discouraged because it is not guaranteed
+            that the arrow renders reasonably. For example, the resulting arrow
+            is affected by the Axes aspect ratio and limits, which may distort
+            the arrow.
+
+            Consider using `~.Axes.annotate` without a text instead, e.g. ::
+
+                ax.annotate("", xytext=(0, 0), xy=(0.5, 0.5),
+                            arrowprops=dict(arrowstyle="->"))
+
         Parameters
         ----------
         %(FancyArrow)s
@@ -5444,17 +5456,6 @@ def arrow(self, x, y, dx, dy, **kwargs):
         -------
         `.FancyArrow`
             The created `.FancyArrow` object.
-
-        Notes
-        -----
-        The resulting arrow is affected by the Axes aspect ratio and limits.
-        This may produce an arrow whose head is not square with its stem. To
-        create an arrow whose head is square with its stem,
-        use :meth:`annotate` for example:
-
-        >>> ax.annotate("", xy=(0.5, 0.5), xytext=(0, 0),
-        ...             arrowprops=dict(arrowstyle="->"))
-
         """
         # Strip away units for the underlying patch since units
         # do not make sense to most patch-like code