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
         -------