@@ -5456,10 +5456,22 @@ def on_changed(collection):
54565456 @_docstring .interpd
54575457 def arrow (self , x , y , dx , dy , ** kwargs ):
54585458 """
5459- Add an arrow to the Axes.
5459+ [*Discouraged*] Add an arrow to the Axes.
54605460
54615461 This draws an arrow from ``(x, y)`` to ``(x+dx, y+dy)``.
54625462
5463+ .. admonition:: Discouraged
5464+
5465+ The use of this method is discouraged because it is not guaranteed
5466+ that the arrow renders reasonably. For example, the resulting arrow
5467+ is affected by the Axes aspect ratio and limits, which may distort
5468+ the arrow.
5469+
5470+ Consider using `~.Axes.annotate` without a text instead, e.g. ::
5471+
5472+ ax.annotate("", xytext=(0, 0), xy=(0.5, 0.5),
5473+ arrowprops=dict(arrowstyle="->"))
5474+
54635475 Parameters
54645476 ----------
54655477 %(FancyArrow)s
@@ -5468,17 +5480,6 @@ def arrow(self, x, y, dx, dy, **kwargs):
54685480 -------
54695481 `.FancyArrow`
54705482 The created `.FancyArrow` object.
5471-
5472- Notes
5473- -----
5474- The resulting arrow is affected by the Axes aspect ratio and limits.
5475- This may produce an arrow whose head is not square with its stem. To
5476- create an arrow whose head is square with its stem,
5477- use :meth:`annotate` for example:
5478-
5479- >>> ax.annotate("", xy=(0.5, 0.5), xytext=(0, 0),
5480- ... arrowprops=dict(arrowstyle="->"))
5481-
54825483 """
54835484 # Strip away units for the underlying patch since units
54845485 # do not make sense to most patch-like code
0 commit comments