Merge pull request matplotlib#16901 from anntzer/docs

Cleanup many docstrings.

Author: timhoffm

examples/images_contours_and_fields/tricontour_smooth_delaunay.py

@@ -19,8 +19,7 @@
 1. Compute an extended mask with a `matplotlib.tri.TriAnalyzer`, which will
    exclude badly shaped (flat) triangles from the border of the
    triangulation. Apply the mask to the triangulation (using set_mask).
-2. Refine and interpolate the data using a
-   `matplotlib.tri.UniformTriRefiner`.
+2. Refine and interpolate the data using a `matplotlib.tri.UniformTriRefiner`.
 3. Plot the refined data with `~.axes.Axes.tricontour`.
 
 """

lib/matplotlib/artist.py

@@ -586,7 +586,7 @@ def set_gid(self, gid):
 
     def get_snap(self):
         """
-        Returns the snap setting.
+        Return the snap setting.
 
         See `.set_snap` for details.
         """
@@ -625,7 +625,7 @@ def set_snap(self, snap):
 
     def get_sketch_params(self):
         """
-        Returns the sketch parameters for the artist.
+        Return the sketch parameters for the artist.
 
         Returns
         -------

lib/matplotlib/axes/_base.py

@@ -1253,10 +1253,9 @@ def set_aspect(self, aspect, adjustable=None, anchor=None, share=False):
         See Also
         --------
         matplotlib.axes.Axes.set_adjustable
-            defining the parameter to adjust in order to meet the required
-            aspect.
+            Set how the Axes adjusts to achieve the required aspect ratio.
         matplotlib.axes.Axes.set_anchor
-            defining the position in case of extra space.
+            Set the position in case of extra space.
         """
         if cbook._str_equal(aspect, 'equal'):
             aspect = 1
@@ -1286,22 +1285,21 @@ def set_aspect(self, aspect, adjustable=None, anchor=None, share=False):
 
     def get_adjustable(self):
         """
-        Returns the adjustable parameter, *{'box', 'datalim'}* that defines
-        which parameter the Axes will change to achieve a given aspect.
+        Return whether the Axes will adjust its physical dimension ('box') or
+        its data limits ('datalim') to achieve the desired aspect ratio.
 
         See Also
         --------
         matplotlib.axes.Axes.set_adjustable
-            defining the parameter to adjust in order to meet the required
-            aspect.
+            Set how the Axes adjusts to achieve the required aspect ratio.
         matplotlib.axes.Axes.set_aspect
-            for a description of aspect handling.
+            For a description of aspect handling.
         """
         return self._adjustable
 
     def set_adjustable(self, adjustable, share=False):
         """
-        Define which parameter the Axes will change to achieve a given aspect.
+        Set how the Axes adjusts to achieve the required aspect ratio.
 
         Parameters
         ----------
@@ -1315,7 +1313,7 @@ def set_adjustable(self, adjustable, share=False):
         See Also
         --------
         matplotlib.axes.Axes.set_aspect
-            for a description of aspect handling.
+            For a description of aspect handling.
 
         Notes
         -----
@@ -1512,12 +1510,11 @@ def apply_aspect(self, position=None):
         See Also
         --------
         matplotlib.axes.Axes.set_aspect
-            for a description of aspect ratio handling.
+            For a description of aspect ratio handling.
         matplotlib.axes.Axes.set_adjustable
-            defining the parameter to adjust in order to meet the required
-            aspect.
+            Set how the Axes adjusts to achieve the required aspect ratio.
         matplotlib.axes.Axes.set_anchor
-            defining the position in case of extra space.
+            Set the position in case of extra space.
         """
         if position is None:
             position = self.get_position(original=True)
@@ -1787,7 +1784,8 @@ def get_yticklines(self):
     # Adding and tracking artists
 
     def _sci(self, im):
-        """Set the current image.
+        """
+        Set the current image.
 
         This image will be the target of colormap functions like
         `~.pyplot.viridis`, and other functions such as `~.pyplot.clim`.  The

lib/matplotlib/axis.py

@@ -1961,8 +1961,8 @@ def _update_offset_text_position(self, bboxes, bboxes2):
 
     def get_text_heights(self, renderer):
         """
-        Returns the amount of space one should reserve for text
-        above and below the axes.  Returns a tuple (above, below)
+        Return how much space should be reserved for text above and below the
+        axes, as a pair of floats.
         """
         bbox, bbox2 = self.get_ticklabel_extents(renderer)
         # MGDTODO: Need a better way to get the pad
@@ -1983,16 +1983,16 @@ def get_text_heights(self, renderer):
 
     def set_ticks_position(self, position):
         """
-        Set the ticks position (top, bottom, both, default or none)
-        both sets the ticks to appear on both positions, but does not
-        change the tick labels.  'default' resets the tick positions to
-        the default: ticks on both positions, labels at bottom.  'none'
-        can be used if you don't want any ticks. 'none' and 'both'
-        affect only the ticks, not the labels.
+        Set the ticks position.
 
         Parameters
         ----------
         position : {'top', 'bottom', 'both', 'default', 'none'}
+            'both' sets the ticks to appear on both positions, but does not
+            change the tick labels.  'default' resets the tick positions to
+            the default: ticks on both positions, labels at bottom.  'none'
+            can be used if you don't want any ticks. 'none' and 'both'
+            affect only the ticks, not the labels.
         """
         cbook._check_in_list(['top', 'bottom', 'both', 'default', 'none'],
                              position=position)
@@ -2123,10 +2123,7 @@ def __init__(self, *args, **kwargs):
         self.offset_text_position = 'left'
 
     def contains(self, mouseevent):
-        """Test whether the mouse event occurred in the y axis.
-
-        Returns *True* | *False*
-        """
+        # docstring inherited
         inside, info = self._default_contains(mouseevent)
         if inside is not None:
             return inside, info
@@ -2271,16 +2268,16 @@ def get_text_widths(self, renderer):
 
     def set_ticks_position(self, position):
         """
-        Set the ticks position (left, right, both, default or none)
-        'both' sets the ticks to appear on both positions, but does not
-        change the tick labels.  'default' resets the tick positions to
-        the default: ticks on both positions, labels at left.  'none'
-        can be used if you don't want any ticks. 'none' and 'both'
-        affect only the ticks, not the labels.
+        Set the ticks position.
 
         Parameters
         ----------
         position : {'left', 'right', 'both', 'default', 'none'}
+            'both' sets the ticks to appear on both positions, but does not
+            change the tick labels.  'default' resets the tick positions to
+            the default: ticks on both positions, labels at left.  'none'
+            can be used if you don't want any ticks. 'none' and 'both'
+            affect only the ticks, not the labels.
         """
         cbook._check_in_list(['left', 'right', 'both', 'default', 'none'],
                              position=position)

lib/matplotlib/backend_bases.py

@@ -826,7 +826,7 @@ def get_gid(self):
 
     def get_snap(self):
         """
-        Returns the snap setting, which can be:
+        Return the snap setting, which can be:
 
         * True: snap vertices to the nearest pixel center
         * False: leave vertices as-is

lib/matplotlib/backends/backend_pdf.py

@@ -2484,9 +2484,7 @@ def savefig(self, figure=None, **kwargs):
             figure.canvas = orig_canvas
 
     def get_pagecount(self):
-        """
-        Returns the current number of pages in the multipage pdf file.
-        """
+        """Return the current number of pages in the multipage pdf file."""
         return len(self._file.pageList)
 
     def attach_note(self, text, positionRect=[-100, -100, 0, 0]):

lib/matplotlib/backends/backend_pgf.py

@@ -152,7 +152,7 @@ def _font_properties_str(prop):
 
 
 def make_pdf_to_png_converter():
-    """Returns a function that converts a pdf file to a png file."""
+    """Return a function that converts a pdf file to a png file."""
     if shutil.which("pdftocairo"):
         def cairo_convert(pdffile, pngfile, dpi):
             cmd = ["pdftocairo", "-singlefile", "-png", "-r", "%d" % dpi,
@@ -1152,7 +1152,5 @@ def savefig(self, figure=None, **kwargs):
             figure.canvas = orig_canvas
 
     def get_pagecount(self):
-        """
-        Returns the current number of pages in the multipage pdf file.
-        """
+        """Return the current number of pages in the multipage pdf file."""
         return self._n_figures

lib/matplotlib/cbook/__init__.py

@@ -1261,7 +1261,7 @@ def contiguous_regions(mask):
 
 def is_math_text(s):
     """
-    Returns whether the string *s* contains math expressions.
+    Return whether the string *s* contains math expressions.
 
     This is done by checking whether *s* contains an even number of
     non-escaped dollar signs.
@@ -1354,10 +1354,11 @@ def _reshape_2D(X, name):
 
 def violin_stats(X, method, points=100, quantiles=None):
     """
-    Returns a list of dictionaries of data which can be used to draw a series
+    Return a list of dictionaries of data which can be used to draw a series
     of violin plots.
 
-    See the Returns section below to view the required keys of the dictionary.
+    See the ``Returns`` section below to view the required keys of the
+    dictionary.
 
     Users can skip this function and pass a user-defined set of dictionaries
     with the same keys to `~.axes.Axes.violinplot` instead of using Matplotlib

lib/matplotlib/collections.py

@@ -514,7 +514,7 @@ def set_offset_position(self, offset_position):
 
     def get_offset_position(self):
         """
-        Returns how offsets are applied for the collection.  If
+        Return how offsets are applied for the collection.  If
         *offset_position* is 'screen', the offset is applied after the
         master transform has been applied, that is, the offsets are in
         screen coordinates.  If offset_position is 'data', the offset
@@ -850,8 +850,7 @@ class _CollectionWithSizes(Collection):
 
     def get_sizes(self):
         """
-        Returns the sizes of the elements in the collection.  The
-        value represents the 'area' of the element.
+        Return the sizes ('areas') of the elements in the collection.
 
         Returns
         -------

lib/matplotlib/figure.py

@@ -886,7 +886,7 @@ def set_size_inches(self, w, h=None, forward=True):
 
     def get_size_inches(self):
         """
-        Returns the current size of the figure in inches.
+        Return the current size of the figure in inches.
 
         Returns
         -------

lib/matplotlib/font_manager.py

@@ -1045,7 +1045,7 @@ def set_default_weight(self, weight):
     # 0.0 (perfect match) and 1.0 (terrible match)
     def score_family(self, families, family2):
         """
-        Returns a match score between the list of font families in
+        Return a match score between the list of font families in
         *families* and the font family name *family2*.
 
         An exact match at the head of the list returns 0.0.
@@ -1078,7 +1078,7 @@ def score_family(self, families, family2):
 
     def score_style(self, style1, style2):
         """
-        Returns a match score between *style1* and *style2*.
+        Return a match score between *style1* and *style2*.
 
         An exact match returns 0.0.
 
@@ -1095,7 +1095,7 @@ def score_style(self, style1, style2):
 
     def score_variant(self, variant1, variant2):
         """
-        Returns a match score between *variant1* and *variant2*.
+        Return a match score between *variant1* and *variant2*.
 
         An exact match returns 0.0, otherwise 1.0.
         """
@@ -1106,7 +1106,7 @@ def score_variant(self, variant1, variant2):
 
     def score_stretch(self, stretch1, stretch2):
         """
-        Returns a match score between *stretch1* and *stretch2*.
+        Return a match score between *stretch1* and *stretch2*.
 
         The result is the absolute value of the difference between the
         CSS numeric values of *stretch1* and *stretch2*, normalized
@@ -1124,7 +1124,7 @@ def score_stretch(self, stretch1, stretch2):
 
     def score_weight(self, weight1, weight2):
         """
-        Returns a match score between *weight1* and *weight2*.
+        Return a match score between *weight1* and *weight2*.
 
         The result is 0.0 if both weight1 and weight 2 are given as strings
         and have the same value.
@@ -1142,7 +1142,7 @@ def score_weight(self, weight1, weight2):
 
     def score_size(self, size1, size2):
         """
-        Returns a match score between *size1* and *size2*.
+        Return a match score between *size1* and *size2*.
 
         If *size2* (the size specified in the font file) is 'scalable', this
         function always returns 0.0, since any font size can be generated.

lib/matplotlib/mathtext.py

@@ -443,17 +443,16 @@ def get_metrics(self, font, font_class, sym, fontsize, dpi, math=True):
 
         Returns an object with the following attributes:
 
-          - *advance*: The advance distance (in points) of the glyph.
+        - *advance*: The advance distance (in points) of the glyph.
 
-          - *height*: The height of the glyph in points.
+        - *height*: The height of the glyph in points.
 
-          - *width*: The width of the glyph in points.
+        - *width*: The width of the glyph in points.
 
-          - *xmin*, *xmax*, *ymin*, *ymax* - the ink rectangle of the glyph
+        - *xmin*, *xmax*, *ymin*, *ymax* - the ink rectangle of the glyph
 
-          - *iceberg* - the distance from the baseline to the top of
-            the glyph.  This corresponds to TeX's definition of
-            "height".
+        - *iceberg* - the distance from the baseline to the top of
+          the glyph.  This corresponds to TeX's definition of "height".
         """
         info = self._get_info(font, font_class, sym, fontsize, dpi, math)
         return info.metrics

lib/matplotlib/patches.py

@@ -1020,30 +1020,16 @@ def __init__(self, xy, closed=True, **kwargs):
         self.set_xy(xy)
 
     def get_path(self):
-        """
-        Get the path of the polygon
-
-        Returns
-        -------
-        Path
-           The `~.path.Path` object for the polygon.
-        """
+        """Get the `.Path` of the polygon."""
         return self._path
 
     def get_closed(self):
-        """
-        Returns if the polygon is closed
-
-        Returns
-        -------
-        bool
-            If the path is closed
-        """
+        """Return whether the polygon is closed."""
         return self._closed
 
     def set_closed(self, closed):
         """
-        Set if the polygon is closed
+        Set whether the polygon is closed.
 
         Parameters
         ----------