Improve docs of markers

timhoffm · timhoffm · commit efb292b46c21 · 2020-06-07T15:43:10.000+02:00
diff --git a/lib/matplotlib/markers.py b/lib/matplotlib/markers.py
@@ -143,6 +143,18 @@
 
 
 class MarkerStyle:
+    """
+    A class representing marker types.
+
+    Attributes
+    ----------
+    markers : list
+        All known markers.
+    filled_markers : list
+        All known filled markers. This is a subset of *markers*.
+    fillstyles : list
+        The supported fillstyles.
+    """
 
     markers = {
         '.': 'point',
@@ -202,18 +214,11 @@ class MarkerStyle:
 
     def __init__(self, marker=None, fillstyle=None):
         """
-        Attributes
-        ----------
-        markers : list of known marks
-
-        fillstyles : list of known fillstyles
-
-        filled_markers : list of known filled markers.
-
         Parameters
         ----------
-        marker : str or array-like, default: None
-            See the descriptions of possible markers in the module docstring.
+        marker : str or array-like or None, default: None
+            *None* means no marker. For other possible marker values see the
+            module docstring `matplotlib.markers`.
 
         fillstyle : str, default: 'full'
             One of 'full', 'left', 'right', 'bottom', 'top', 'none'.
@@ -249,11 +254,13 @@ def get_fillstyle(self):
 
     def set_fillstyle(self, fillstyle):
         """
-        Sets fillstyle
+        Set the fillstyle.
 
         Parameters
         ----------
-        fillstyle : string amongst known fillstyles
+        fillstyle : {'full', 'left', 'right', 'bottom', 'top', 'none'}
+            The part of the marker surface that is colored with
+            markerfacecolor.
         """
         if fillstyle is None:
             fillstyle = rcParams['markers.fillstyle']
@@ -271,6 +278,15 @@ def get_marker(self):
         return self._marker
 
     def set_marker(self, marker):
+        """
+        Set the marker.
+
+        Parameters
+        ----------
+        marker : str or array-like or None, default: None
+            *None* means no marker. For other possible marker values see the
+            module docstring `matplotlib.markers`.
+        """
         if (isinstance(marker, np.ndarray) and marker.ndim == 2 and
                 marker.shape[1] == 2):
             self._marker_function = self._set_vertices
@@ -300,15 +316,35 @@ def set_marker(self, marker):
             self._recache()
 
     def get_path(self):
+        """
+        Return a `.Path` for the primary part of the marker.
+
+        For unfilled markers this is the whole marker, for filled markers,
+        this is the area to be drawn with *markerfacecolor*.
+        """
         return self._path
 
     def get_transform(self):
+        """
+        Return the transform to be applied to the `.Path` from
+        `MarkerStyle.get_path()`.
+        """
         return self._transform.frozen()
 
     def get_alt_path(self):
+        """
+        Return a `.Path` for the alternate part of the marker.
+
+        For unfilled markers, this is *None*; for filled markers, this is the
+        area to be drawn with *markerfacecoloralt*.
+        """
         return self._alt_path
 
     def get_alt_transform(self):
+        """
+        Return the transform to be applied to the `.Path` from
+        `MarkerStyle.get_alt_path()`.
+        """
         return self._alt_transform.frozen()
 
     def get_snap_threshold(self):
