improve Axes.stem docstring

timhoffm · timhoffm · commit d7be98fc6b1a · 2018-01-04T01:34:51.000+01:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -2392,27 +2392,78 @@ def broken_barh(self, xranges, yrange, **kwargs):
     @_preprocess_data(replace_all_args=True, label_namer=None)
     def stem(self, *args, **kwargs):
         """
+        stem(*args, linefmt=None, markerfmt=None, basefmt=None, data=None,
+        bottom=0, label=None)
+
         Create a stem plot.
 
         Call signatures::
 
-          stem(y, linefmt='b-', markerfmt='bo', basefmt='r-')
-          stem(x, y, linefmt='b-', markerfmt='bo', basefmt='r-')
+          stem(y)
+          stem(x, y)
+
+        A stem plot plots vertical lines at each *x* location from the baseline
+        to *y*, and places a marker there.
+
+
+        Parameters
+        ----------
+        x : array-like, optional
+            The x-positions of the stems. Default: (0, 1, ..., len(y) - 1).
+
+        y : array-like
+            The y-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:
+
+            =========  =============
+            Character  Line Style
+            =========  =============
+            ``'-'``    solid line
+            ``'--'``   dashed line
+            ``'-.'``   dash-dot line
+            ``':'``    dotted line
+            =========  =============
+
+            Default: 'C0-', i.e. solid line with the first color of the color
+            cycle.
 
-        A stem plot plots vertical lines (using *linefmt*) at each *x*
-        location from the baseline to *y*, and places a marker there
-        using *markerfmt*.  A horizontal line at 0 is plotted using
-        *basefmt*.
+            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 reasonable plot.
+
+        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.
+
+        basefmt : str, optional
+            A format string defining the properties of the baseline.
+
+            Default: 'C3-' ('C2-' in classic mode).
+
+        bottom : float, optional, default: 0
+            The y-position of the baseline.
+
+        label : str, optional, default: None
+            The label to use for the stems in legends.
+
+
+        Returns
+        -------
+        a :class:`~matplotlib.container.StemContainer`
 
-        If no *x* values are provided, the default is (0, 1, ..., len(y) - 1)
+        The stemcontainer may be treated like a tuple
+        (*markerline*, *stemlines*, *baseline*)
 
-        Return value is a tuple (*markerline*, *stemlines*,
-        *baseline*). See :class:`~matplotlib.container.StemContainer`
 
         .. seealso::
-            This
-            `document <http://www.mathworks.com/help/techdoc/ref/stem.html>`_
-            for details.
+            The MATLAB function
+            `stem <http://www.mathworks.com/help/techdoc/ref/stem.html>`_
+            which inspired this method.
 
         """
         remember_hold = self._hold
diff --git a/lib/matplotlib/container.py b/lib/matplotlib/container.py
@@ -10,6 +10,9 @@
 class Container(tuple):
     """
     Base class for containers.
+
+    Containers are classes that collect semantically related Artists such as
+    the bars of a bar plot.
     """
 
     def __repr__(self):
@@ -107,6 +110,25 @@ def get_children(self):
 
 
 class BarContainer(Container):
+    """
+    Container for the artists of bar plots.
+
+    E.g. created in a :meth:`.Axes.bar` plot.
+
+    The container can be treated as a tuple of the *patches* themselves.
+    Additionally, you can access these and further parameters by the
+    attributes.
+
+    Attributes
+    ----------
+    patches : list of :class:`~matplotlib.patches.Rectangle`
+        The artists of the bars.
+
+    errorbar : None or :class:`~matplotlib.container.ErrorbarContainer`
+        A container for the error bar artists if error bars are present.
+        *None* otherwise.
+
+    """
 
     def __init__(self, patches, errorbar=None, **kwargs):
         self.patches = patches
@@ -115,8 +137,14 @@ def __init__(self, patches, errorbar=None, **kwargs):
 
 
 class ErrorbarContainer(Container):
-    '''
-    Container for errobars.
+    """
+    Container for the artists of error bars.
+
+    E.g. created in a :meth:`.Axes.errorbar` plot.
+
+    The container can be treated as the *lines* tuple itself.
+    Additionally, you can access these and further parameters by the
+    attributes.
 
     Attributes
     ----------
@@ -132,7 +160,8 @@ class ErrorbarContainer(Container):
 
     has_xerr, has_yerr : bool
         ``True`` if the errorbar has x/y errors.
-    '''
+
+    """
 
     def __init__(self, lines, has_xerr=False, has_yerr=False, **kwargs):
         self.lines = lines
@@ -142,6 +171,24 @@ def __init__(self, lines, has_xerr=False, has_yerr=False, **kwargs):
 
 
 class StemContainer(Container):
+    """
+    Container for the artists created in a :meth:`.Axes.stem` plot.
+
+    The container can be treated like a namedtuple ``(markerline, stemlines,
+    baseline)``.
+
+    Attributes
+    ----------
+    markerline :  :class:`~matplotlib.lines.Line2D`
+        The artist of the markers at the stem heads.
+
+    stemlines : list of :class:`~matplotlib.lines.Line2D`
+        The artists of the vertical lines for all stems.
+
+    baseline : :class:`~matplotlib.lines.Line2D`
+        The artist of the horizontal baseline.
+
+    """
 
     def __init__(self, markerline_stemlines_baseline, **kwargs):
         markerline, stemlines, baseline = markerline_stemlines_baseline
