@@ -2335,7 +2335,7 @@ def get_styles(cls):
23352335@classmethod
23362336def pprint_styles (cls ):
23372337"""Return the available styles as pretty-printed string."""
2338- table = [('Class' ,'Name' ,'Attrs ' ),
2338+ table = [('Class' ,'Name' ,'Parameters ' ),
23392339* [(cls .__name__ ,
23402340# Add backquotes, as - and | have special meaning in reST.
23412341f'``{ name } ,
@@ -4159,49 +4159,90 @@ def __init__(self, posA=None, posB=None, *,
41594159patchA = None ,patchB = None ,shrinkA = 2 ,shrinkB = 2 ,
41604160mutation_scale = 1 ,mutation_aspect = 1 ,** kwargs ):
41614161"""
4162- There are two ways for defining an arrow:
4162+ **Defining the arrow position and path**
41634163
4164- - If *posA* and *posB* are given, a path connecting two points is
4165- created according to *connectionstyle*. The path will be
4166- clipped with *patchA* and *patchB* and further shrunken by
4167- *shrinkA* and *shrinkB*. An arrow is drawn along this
4168- resulting path using the *arrowstyle* parameter.
4164+ There are two ways to define the arrow position and path:
41694165
4170- - Alternatively if *path* is provided, an arrow is drawn along this
4171- path and *patchA*, *patchB*, *shrinkA*, and *shrinkB* are ignored.
4166+ - **Start, end and connection**:
4167+ The typical approach is to define the start and end points of the
4168+ arrow using *posA* and *posB*. The curve between these two can
4169+ further be configured using *connectionstyle*.
4170+
4171+ If given, the arrow curve is clipped by *patchA* and *patchB*,
4172+ allowing it to start/end at the border of these patches.
4173+ Additionally, the arrow curve can be shortened by *shrinkA* and *shrinkB*
4174+ to create a margin between start/end (after possible clipping) and the
4175+ drawn arrow.
4176+
4177+ - **path**: Alternatively if *path* is provided, an arrow is drawn along
4178+ this Path. In this case, *connectionstyle*, *patchA*, *patchB*,
4179+ *shrinkA*, and *shrinkB* are ignored.
4180+
4181+ **Styling**
4182+
4183+ The *arrowstyle* defines the styling of the arrow head, tail and shaft.
4184+ The resulting arrows can be styled further by setting the `.Patch`
4185+ properties such as *linewidth*, *color*, *facecolor*, *edgecolor*
4186+ etc. via keyword arguments.
41724187
41734188 Parameters
41744189 ----------
4175- posA, posB : (float, float), default: None
4176- (x, y) coordinates of arrow tail and arrow head respectively.
4190+ posA, posB : (float, float), optional
4191+ (x, y) coordinates of start and end point of the arrow.
4192+ The actually drawn start and end positions may be modified
4193+ through *patchA*, *patchB*, *shrinkA*, and *shrinkB*.
41774194
4178- path : `~matplotlib.path.Path`, default: None
4195+ *posA*, *posB* are exclusive of *path*.
4196+
4197+ path : `~matplotlib.path.Path`, optional
41794198 If provided, an arrow is drawn along this path and *patchA*,
41804199 *patchB*, *shrinkA*, and *shrinkB* are ignored.
41814200
4201+ *path* is exclusive of *posA*, *posB*.
4202+
41824203 arrowstyle : str or `.ArrowStyle`, default: 'simple'
4183- The `.ArrowStyle` with which the fancy arrow is drawn. If a
4184- string, it should be one of the available arrowstyle names, with
4185- optional comma-separated attributes. The optional attributes are
4186- meant to be scaled with the *mutation_scale*. The following arrow
4187- styles are available:
4204+ The styling of arrow head, tail and shaft. This can be
4205+
4206+ - `.ArrowStyle` or one of its subclasses
4207+ - The shorthand string name (e.g. "->") as given in the table below,
4208+ optionally containing a comma-separated list of style parameters,
4209+ e.g. "->, head_length=10, head_width=5".
4210+
4211+ The style parameters are scaled by *mutation_scale*.
4212+
4213+ The following arrow styles are available. See also
4214+ :doc:`/gallery/text_labels_and_annotations/fancyarrow_demo`.
41884215
41894216 %(ArrowStyle:table)s
41904217
4218+ Only the styles ``<|-``, ``-|>``, ``<|-|>`` ``simple``, ``fancy``
4219+ and ``wedge`` contain closed paths and can be filled.
4220+
41914221 connectionstyle : str or `.ConnectionStyle` or None, optional,\
41924222
4193- The `.ConnectionStyle` with which *posA* and *posB* are connected.
4194- If a string, it should be one of the available connectionstyle
4195- names, with optional comma-separated attributes. The following
4196- connection styles are available:
4223+ `.ConnectionStyle` with which *posA* and *posB* are connected.
4224+ This can be
4225+
4226+ - `.ConnectionStyle` or one of its subclasses
4227+ - The shorthand string name as given in the table below, e.g. "arc3".
41974228
41984229 %(ConnectionStyle:table)s
41994230
4231+ Ignored if *path* is provided.
4232+
42004233 patchA, patchB : `~matplotlib.patches.Patch`, default: None
4201- Head and tail patches, respectively.
4234+ Optional Patches at *posA* and *posB*, respectively. If given,
4235+ the arrow path is clipped by these patches such that head and tail
4236+ are at the border of the patches.
4237+
4238+ Ignored if *path* is provided.
42024239
42034240 shrinkA, shrinkB : float, default: 2
4204- Shrink amount, in points, of the tail and head of the arrow respectively.
4241+ Shorten the arrow path at *posA* and *posB* by this amount in points.
4242+ This allows to add a margin between the intended start/end points and
4243+ the arrow.
4244+
4245+ Ignored if *path* is provided.
42054246
42064247 mutation_scale : float, default: 1
42074248 Value with which attributes of *arrowstyle* (e.g., *head_length*)