Improve docstrings of Line2D

timhoffm · timhoffm · commit b4b45678ac90 · 2018-08-25T16:39:36.000+02:00
diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
@@ -492,7 +492,7 @@ def contains(self, mouseevent):
         return len(ind) > 0, dict(ind=ind)
 
     def get_pickradius(self):
-        """return the pick radius used for containment tests"""
+        """Return the pick radius used for containment tests."""
         return self.pickradius
 
     def set_pickradius(self, d):
@@ -507,18 +507,27 @@ def set_pickradius(self, d):
 
     def get_fillstyle(self):
         """
-        return the marker fillstyle
+        Return the marker fillstyle.
         """
         return self._marker.get_fillstyle()
 
     def set_fillstyle(self, fs):
         """
-        Set the marker fill style; 'full' means fill the whole marker.
-        'none' means no filling; other options are for half-filled markers.
+        Set the marker fill style.
 
         Parameters
         ----------
         fs : {'full', 'left', 'right', 'bottom', 'top', 'none'}
+            Possible values:
+
+            - 'full': Fill the whole marker with the *markerfacecolor*.
+            - 'left', 'right', 'bottom', 'top': Fill the marker half at
+              the given side with the *markerfacecolor*. The other
+              half of the marker is filled with *markerfacecoloralt*.
+            - 'none': No filling.
+
+            For examples see
+            :doc:`/gallery/lines_bars_and_markers/marker_fillstyle_reference`.
         """
         self._marker.set_fillstyle(fs)
         self.stale = True
@@ -576,7 +585,7 @@ def set_markevery(self, every):
         self._markevery = every
 
     def get_markevery(self):
-        """return the markevery setting"""
+        """Return the markevery setting."""
         return self._markevery
 
     def set_picker(self, p):
@@ -619,7 +628,7 @@ def axes(self, ax):
 
     def set_data(self, *args):
         """
-        Set the x and y data
+        Set the x and y data.
 
         ACCEPTS: 2D array (rows are x, y) or two 1D arrays
         """
@@ -702,7 +711,7 @@ def _get_transformed_path(self):
 
     def set_transform(self, t):
         """
-        set the Transformation instance used by this artist
+        Set the Transformation instance used by this artist.
 
         Parameters
         ----------
@@ -714,13 +723,13 @@ def set_transform(self, t):
         self.stale = True
 
     def _is_sorted(self, x):
-        """return True if x is sorted in ascending order"""
+        """Return whether x is sorted in ascending order."""
         # We don't handle the monotonically decreasing case.
         return _path.is_sorted(x)
 
     @allow_rasterization
     def draw(self, renderer):
-        """draw the Line with `renderer` unless visibility is False"""
+        """Draw the Line with *renderer* unless visibility is *False*."""
         if not self.get_visible():
             return
 
@@ -851,9 +860,11 @@ def draw(self, renderer):
         self.stale = False
 
     def get_antialiased(self):
+        """Return whether antialiased rendering is used."""
         return self._antialiased
 
     def get_color(self):
+        """Return the line color."""
         return self._color
 
     def get_drawstyle(self):
@@ -967,7 +978,7 @@ def set_antialiased(self, b):
 
     def set_color(self, color):
         """
-        Set the color of the line
+        Set the color of the line.
 
         Parameters
         ----------
@@ -978,16 +989,27 @@ def set_color(self, color):
 
     def set_drawstyle(self, drawstyle):
         """
-        Set the drawstyle of the plot
+        Set the drawstyle of the plot.
 
-        'default' connects the points with lines. The steps variants
-        produce step-plots. 'steps' is equivalent to 'steps-pre' and
-        is maintained for backward-compatibility.
+        The drawstyle determines how the points are connected.
 
         Parameters
         ----------
         drawstyle : {'default', 'steps', 'steps-pre', 'steps-mid', \
 'steps-post'}
+            Possible values:
+
+            - 'default': The points are connected with straight lines.
+            - 'steps-pre', 'steps-mid', 'steps-post': The points are
+              connected with step-like lines, i.e. horizontal lines with
+              vertical steps.
+              The postfix pre/mid/post determines the position of the vertical
+              step (before the line segment, i.e. directly after the left
+              point / halfway between the points / after the line segment,
+              i.e. directly before the right point).
+            - 'steps' is equal to 'steps-pre' and is maintained for
+              backward-compatibility.
+
         """
         if drawstyle is None:
             drawstyle = 'default'
@@ -1001,7 +1023,7 @@ def set_drawstyle(self, drawstyle):
 
     def set_linewidth(self, w):
         """
-        Set the line width in points
+        Set the line width in points.
 
         Parameters
         ----------
@@ -1017,9 +1039,10 @@ def set_linewidth(self, w):
             self._us_dashOffset, self._us_dashSeq, self._linewidth)
 
     def _split_drawstyle_linestyle(self, ls):
-        '''Split drawstyle from linestyle string
+        """
+        Split drawstyle from linestyle string.
 
-        If `ls` is only a drawstyle default to returning a linestyle
+        If *ls* is only a drawstyle default to returning a linestyle
         of '-'.
 
         Parameters
@@ -1035,48 +1058,43 @@ def _split_drawstyle_linestyle(self, ls):
 
         ls : str
             The linestyle with the drawstyle (if any) stripped.
-        '''
+        """
         for ds in self.drawStyleKeys:  # long names are first in the list
             if ls.startswith(ds):
                 return ds, ls[len(ds):] or '-'
         return None, ls
 
     def set_linestyle(self, ls):
         """
-        Set the linestyle of the line (also accepts drawstyles,
-        e.g., ``'steps--'``)
-
-
-        ===========================   =================
-        linestyle                     description
-        ===========================   =================
-        ``'-'`` or ``'solid'``        solid line
-        ``'--'`` or  ``'dashed'``     dashed line
-        ``'-.'`` or  ``'dashdot'``    dash-dotted line
-        ``':'`` or ``'dotted'``       dotted line
-        ``'None'``                    draw nothing
-        ``' '``                       draw nothing
-        ``''``                        draw nothing
-        ===========================   =================
+        Set the linestyle of the line.
 
-        'steps' is equivalent to 'steps-pre' and is maintained for
-        backward-compatibility.
+        Parameters
+        ----------
+        ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
+            Possible values:
 
-        Alternatively a dash tuple of the following form can be provided::
+            - A string:
 
-            (offset, onoffseq),
+              ===============================   =================
+              Linestyle                         Description
+              ===============================   =================
+              ``'-'`` or ``'solid'``            solid line
+              ``'--'`` or  ``'dashed'``         dashed line
+              ``'-.'`` or  ``'dashdot'``        dash-dotted line
+              ``':'`` or ``'dotted'``           dotted line
+              ``'None'`` or ``' '`` or ``''``   draw nothing
+              ===============================   =================
 
-        where ``onoffseq`` is an even length tuple of on and off ink in points.
+              Optionally, the string may be preceded by a drawstyle, e.g.
+              ``'steps--'``. See :meth:`set_drawstyle` for details.
 
-        .. seealso::
+            - Alternatively a dash tuple of the following form can be
+              provided::
 
-            :meth:`set_drawstyle`
-               To set the drawing style (stepping) of the plot.
+                  (offset, onoffseq)
 
-        Parameters
-        ----------
-        ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
-            The line style.
+              where ``onoffseq`` is an even length tuple of on and off ink
+              in points. See also :meth:`set_dashes`.
         """
         if isinstance(ls, str):
             ds, ls = self._split_drawstyle_linestyle(ls)
@@ -1110,7 +1128,7 @@ def set_marker(self, marker):
 
         Parameters
         ----------
-        marker: marker style
+        marker : marker style
             See `~matplotlib.markers` for full description of possible
             arguments.
         """
@@ -1213,13 +1231,19 @@ def set_ydata(self, y):
 
     def set_dashes(self, seq):
         """
-        Set the dash sequence, sequence of dashes with on off ink in
-        points.  If seq is empty or if seq = (None, None), the
-        linestyle will be set to solid.
+        Set the dash sequence.
+
+        The dash sequence is a sequence of floats of even length describing
+        the length of dashes and spaces in points.
+
+        For example, (5, 2, 1, 2) describes a sequence of 5 point and 1 point
+        dashes separated by 2 point spaces.
 
         Parameters
         ----------
         seq : sequence of floats (on/off ink in points) or (None, None)
+            If *seq* is empty or ``(None, None)``, the linestyle will be set
+            to solid.
         """
         if seq == (None, None) or len(seq) == 0:
             self.set_linestyle('-')
@@ -1258,6 +1282,7 @@ def set_dash_joinstyle(self, s):
         Parameters
         ----------
         s : {'miter', 'round', 'bevel'}
+            For examples see :doc:`/gallery/lines_bars_and_markers/joinstyle`.
         """
         s = s.lower()
         if s not in self.validJoin:
@@ -1274,6 +1299,7 @@ def set_solid_joinstyle(self, s):
         Parameters
         ----------
         s : {'miter', 'round', 'bevel'}
+            For examples see :doc:`/gallery/lines_bars_and_markers/joinstyle`.
         """
         s = s.lower()
         if s not in self.validJoin:
@@ -1286,13 +1312,13 @@ def set_solid_joinstyle(self, s):
 
     def get_dash_joinstyle(self):
         """
-        Get the join style for dashed linestyles
+        Get the join style for dashed linestyles.
         """
         return self._dashjoinstyle
 
     def get_solid_joinstyle(self):
         """
-        Get the join style for solid linestyles
+        Get the join style for solid linestyles.
         """
         return self._solidjoinstyle
 
@@ -1330,18 +1356,18 @@ def set_solid_capstyle(self, s):
 
     def get_dash_capstyle(self):
         """
-        Get the cap style for dashed linestyles
+        Get the cap style for dashed linestyles.
         """
         return self._dashcapstyle
 
     def get_solid_capstyle(self):
         """
-        Get the cap style for solid linestyles
+        Get the cap style for solid linestyles.
         """
         return self._solidcapstyle
 
     def is_dashed(self):
-        'return True if line is dashstyle'
+        """Return whether line is dashstyle."""
         return self._linestyle in ('--', '-.', ':')
 
 
