Cleanup stem docs and simplify implementation.

anntzer · anntzer · commit aa5af778a802 · 2020-11-11T21:59:28.000+01:00
On the implementation side, we can use `vlines`/`hlines` to generate the
correct `LineCollection`.

On the documentation side, it seems perfectly valid to only specify a
linestyle and no color in `linefmt` (e.g.
`stem([0, 1], [2, 3], linefmt="-.")` works just fine).  On the other
hand markers are indeed silently dropped (possibly we could emit a
warning there, but that should be another PR).  So reword accordingly;
and also slighly reword the doc for `markerfmt`.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -2614,8 +2614,7 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
             For horizontal stem plots, the x-values of the stem heads.
 
         linefmt : str, optional
-            A string defining the properties of the vertical lines. Usually,
-            this will be a color or a color and a linestyle:
+            A string defining the color and/or linestyle of the vertical lines:
 
             =========  =============
             Character  Line Style
@@ -2629,15 +2628,14 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
             Default: 'C0-', i.e. solid line with the first color of the color
             cycle.
 
-            Note: While it is technically possible to specify valid formats
-            other than color or color and linestyle (e.g. 'rx' or '-.'), this
-            is beyond the intention of the method and will most likely not
-            result in a reasonable plot.
+            Note: Markers specified through this parameter (e.g. 'x') will be
+            silently ignored (unless using ``use_line_collection=False``).
+            Instead, markers should be specified using *markerfmt*.
 
         markerfmt : str, optional
-            A string defining the properties of the markers at the stem heads.
-            Default: 'C0o', i.e. filled circles with the first color of the
-            color cycle.
+            A string defining the color and/or shape of the markers at the stem
+            heads.  Default: 'C0o', i.e. filled circles with the first color of
+            the color cycle.
 
         basefmt : str, default: 'C3-' ('C2-' in classic mode)
             A format string defining the properties of the baseline.
@@ -2738,20 +2736,12 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
 
         # New behaviour in 3.1 is to use a LineCollection for the stemlines
         if use_line_collection:
-            if orientation == 'horizontal':
-                stemlines = [
-                    ((bottom, loc), (head, loc))
-                    for loc, head in zip(locs, heads)]
-            else:
-                stemlines = [
-                    ((loc, bottom), (loc, head))
-                    for loc, head in zip(locs, heads)]
             if linestyle is None:
                 linestyle = rcParams['lines.linestyle']
-            stemlines = mcoll.LineCollection(stemlines, linestyles=linestyle,
-                                             colors=linecolor,
-                                             label='_nolegend_')
-            self.add_collection(stemlines)
+            xlines = self.vlines if orientation == "vertical" else self.hlines
+            stemlines = xlines(
+                locs, bottom, heads,
+                colors=linecolor, linestyles=linestyle, label="_nolegend_")
         # Old behaviour is to plot each of the lines individually
         else:
             stemlines = []
