Clarify current behavior of draw_path_collection.

anntzer · anntzer · commit 44c209a8a4ea · 2021-12-15T14:09:20.000+01:00
Note that the definition of "corresponding entry" is intentionally left
a bit vague, because the current behavior is in fact not consistent
between backends and will need to be harmonized first.  The goal of this
change here is mostly to describe the order in which `master_transform`,
`all_transforms`, and `offsetTrans` are applied.
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -223,12 +223,15 @@ def draw_path_collection(self, gc, master_transform, paths, all_transforms,
                              linewidths, linestyles, antialiaseds, urls,
                              offset_position):
         """
-        Draw a collection of paths selecting drawing properties from
-        the lists *facecolors*, *edgecolors*, *linewidths*,
-        *linestyles* and *antialiaseds*. *offsets* is a list of
-        offsets to apply to each of the paths.  The offsets in
-        *offsets* are first transformed by *offsetTrans* before being
-        applied.
+        Draw a collection of paths.
+
+        Each paths is first transformed by the corresponding entry
+        in *all_transforms* (a list of (3, 3) matrices) and then by
+        *master_transform*.  They are then translated by the corresponding
+        entry in *offsets*, which has been first transformed by *offsetTrans*.
+
+        *facecolors*, *edgecolors*, *linewidths*, *linestules*, and
+        *antialiased* are lists that set the corresponding properties.
 
         *offset_position* is unused now, but the argument is kept for
         backwards compatibility.
