@@ -5471,10 +5471,22 @@ def on_changed(collection):
54715471@_docstring .interpd
54725472def arrow (self ,x ,y ,dx ,dy ,** kwargs ):
54735473"""
5474- Add an arrow to the Axes.
5474+ [*Discouraged*] Add an arrow to the Axes.
54755475
54765476 This draws an arrow from ``(x, y)`` to ``(x+dx, y+dy)``.
54775477
5478+ .. admonition:: Discouraged
5479+
5480+ The use of this method is discouraged because it is not guaranteed
5481+ that the arrow renders reasonably. For example, the resulting arrow
5482+ is affected by the Axes aspect ratio and limits, which may distort
5483+ the arrow.
5484+
5485+ Consider using `~.Axes.annotate` without a text instead, e.g. ::
5486+
5487+ ax.annotate("", xytext=(0, 0), xy=(0.5, 0.5),
5488+ arrowprops=dict(arrowstyle="->"))
5489+
54785490 Parameters
54795491 ----------
54805492 %(FancyArrow)s
@@ -5483,17 +5495,6 @@ def arrow(self, x, y, dx, dy, **kwargs):
54835495 -------
54845496 `.FancyArrow`
54855497 The created `.FancyArrow` object.
5486-
5487- Notes
5488- -----
5489- The resulting arrow is affected by the Axes aspect ratio and limits.
5490- This may produce an arrow whose head is not square with its stem. To
5491- create an arrow whose head is square with its stem,
5492- use :meth:`annotate` for example:
5493-
5494- >>> ax.annotate("", xy=(0.5, 0.5), xytext=(0, 0),
5495- ... arrowprops=dict(arrowstyle="->"))
5496-
54975498 """
54985499# Strip away units for the underlying patch since units
54995500# do not make sense to most patch-like code