Reword some docstrings.

anntzer · anntzer · commit 0f4aa6b07b1e · 2019-11-24T12:49:26.000+01:00
For many parameters, reword their description from "Control the foo" or
"Specifies the foo" to "The foo", which is just as clear.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -1258,12 +1258,12 @@ def eventplot(self, positions, orientation='horizontal', lineoffsets=1,
             *orientation* parameter).
 
         orientation : {'horizontal', 'vertical'}, optional
-            Controls the direction of the event collections:
+            The direction of the event collections:
 
-                - 'horizontal' : the lines are arranged horizontally in rows,
-                  and are vertical.
-                - 'vertical' : the lines are arranged vertically in columns,
-                  and are horizontal.
+            - 'horizontal': the lines are arranged horizontally in rows,
+              and are vertical.
+            - 'vertical': the lines are arranged vertically in columns,
+              and are horizontal.
 
         lineoffsets : scalar or sequence of scalars, optional, default: 1
             The offset of the center of the lines from the origin, in the
@@ -2910,7 +2910,7 @@ def pie(self, x, explode=None, labels=None, colors=None,
         textprops : dict, optional, default: None
             Dict of arguments to pass to the text objects.
 
-        center :  list of float, optional, default: (0, 0)
+        center : list of float, optional, default: (0, 0)
             Center position of the chart. Takes value (0, 0) or is a sequence
             of 2 scalars.
 
@@ -3492,7 +3492,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
         x : Array or a sequence of vectors.
             The input data.
 
-        notch : bool, optional (False)
+        notch : bool, optional, default: False
             If `True`, will produce a notched box plot. Otherwise, a
             rectangular boxplot is produced. The notches represent the
             confidence interval (CI) around the median. See the entry
@@ -3514,9 +3514,9 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
             fliers default to 'b+'  If you want more control use the
             flierprops kwarg.
 
-        vert : bool, optional (True)
-            If `True` (default), makes the boxes vertical. If `False`,
-            everything is drawn horizontally.
+        vert : bool, optional, default: True
+            If `True`, draws vertical boxes.
+            If `False`, draw horizontal boxes.
 
         whis : float or (float, float) (default = 1.5)
             The position of the whiskers.
@@ -3576,55 +3576,55 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
             sequence. The default is 0.5, or ``0.15*(distance between
             extreme positions)``, if that is smaller.
 
-        patch_artist : bool, optional (False)
+        patch_artist : bool, optional, default: False
             If `False` produces boxes with the Line2D artist. Otherwise,
             boxes and drawn with Patch artists.
 
         labels : sequence, optional
             Labels for each dataset. Length must be compatible with
             dimensions of ``x``.
 
-        manage_ticks : bool, optional (True)
+        manage_ticks : bool, optional, default: True
             If True, the tick locations and labels will be adjusted to match
             the boxplot positions.
 
-        autorange : bool, optional (False)
+        autorange : bool, optional, default: False
             When `True` and the data are distributed such that the 25th and
             75th percentiles are equal, ``whis`` is set to (0, 100) such
             that the whisker ends are at the minimum and maximum of the data.
 
-        meanline : bool, optional (False)
+        meanline : bool, optional, default: False
             If `True` (and ``showmeans`` is `True`), will try to render
             the mean as a line spanning the full width of the box
             according to ``meanprops`` (see below). Not recommended if
             ``shownotches`` is also True. Otherwise, means will be shown
             as points.
 
-        zorder : scalar, optional (None)
+        zorder : scalar, optional, default: None
             Sets the zorder of the boxplot.
 
         Other Parameters
         ----------------
-        showcaps : bool, optional (True)
+        showcaps : bool, optional, default: True
             Show the caps on the ends of whiskers.
-        showbox : bool, optional (True)
+        showbox : bool, optional, default: True
             Show the central box.
-        showfliers : bool, optional (True)
+        showfliers : bool, optional, default: True
             Show the outliers beyond the caps.
-        showmeans : bool, optional (False)
+        showmeans : bool, optional, default: False
             Show the arithmetic means.
-        capprops : dict, optional (None)
-            Specifies the style of the caps.
-        boxprops : dict, optional (None)
-            Specifies the style of the box.
-        whiskerprops : dict, optional (None)
-            Specifies the style of the whiskers.
-        flierprops : dict, optional (None)
-            Specifies the style of the fliers.
-        medianprops : dict, optional (None)
-            Specifies the style of the median.
-        meanprops : dict, optional (None)
-            Specifies the style of the mean.
+        capprops : dict, optional, default: None
+            The style of the caps.
+        boxprops : dict, optional, default: None
+            The style of the box.
+        whiskerprops : dict, optional, default: None
+            The style of the whiskers.
+        flierprops : dict, optional, default: None
+            The style of the fliers.
+        medianprops : dict, optional, default: None
+            The style of the median.
+        meanprops : dict, optional, default: None
+            The style of the mean.
 
         Returns
         -------
@@ -5497,9 +5497,9 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
             This parameter is ignored for RGB(A) data.
 
         aspect : {'equal', 'auto'} or float, optional
-            Controls the aspect ratio of the axes. The aspect is of particular
-            relevance for images since it may distort the image, i.e. pixel
-            will not be square.
+            The aspect ratio of the axes.  This parameter is particularly
+            relevant for images since it determines whether data pixels are
+            square.
 
             This parameter is a shortcut for explicitly calling
             `.Axes.set_aspect`. See there for further details.
@@ -6504,7 +6504,7 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
             Default is 'bar'
 
         align : {'left', 'mid', 'right'}, optional
-            Controls how the histogram is plotted.
+            The horizontal alignment of the histogram bars.
 
             - 'left': bars are centered on the left bin edges.
             - 'mid': bars are centered between the bin edges.
@@ -7682,11 +7682,10 @@ def spy(self, Z, precision=0, marker=None, markersize=None,
             matrices and images.
             If not given, :rc:`image.origin` is used, defaulting to 'upper'.
 
-
-        aspect : {'equal', 'auto', None} or float, optional
-            Controls the aspect ratio of the axes. The aspect is of particular
-            relevance for images since it may distort the image, i.e. pixel
-            will not be square.
+        aspect : {'equal', 'auto', None} or float, optional, default: 'equal'
+            The aspect ratio of the axes.  This parameter is particularly
+            relevant for images since it determines whether data pixels are
+            square.
 
             This parameter is a shortcut for explicitly calling
             `.Axes.set_aspect`. See there for further details.
@@ -7697,8 +7696,6 @@ def spy(self, Z, precision=0, marker=None, markersize=None,
               non-square pixels.
             - *None*: Use :rc:`image.aspect`.
 
-            Default: 'equal'
-
         Returns
         -------
         ret : `~matplotlib.image.AxesImage` or `.Line2D`
diff --git a/lib/matplotlib/mlab.py b/lib/matplotlib/mlab.py
@@ -152,12 +152,11 @@ def detrend(x, key=None, axis=None):
         Array or sequence containing the data.
 
     key : {'default', 'constant', 'mean', 'linear', 'none'} or function
-        Specifies the detrend algorithm to use. 'default' is 'mean', which is
-        the same as `detrend_mean`. 'constant' is the same. 'linear' is
-        the same as `detrend_linear`. 'none' is the same as
-        `detrend_none`. The default is 'mean'. See the corresponding
-        functions for more details regarding the algorithms. Can also be a
-        function that carries out the detrend operation.
+        The detrending algorithm to use. 'default', 'mean', and 'constant' are
+        the same as `detrend_mean`. 'linear' is the same as `detrend_linear`.
+        'none' is the same as `detrend_none`. The default is 'mean'. See the
+        corresponding functions for more details regarding the algorithms. Can
+        also be a function that carries out the detrend operation.
 
     axis : integer
         The axis along which to do the detrending.
@@ -629,10 +628,9 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
         version of the segment.
 
     sides : {'default', 'onesided', 'twosided'}
-        Specifies which sides of the spectrum to return.  Default gives the
-        default behavior, which returns one-sided for real data and both
-        for complex data.  'onesided' forces the return of a one-sided
-        spectrum, while 'twosided' forces two-sided.
+        Which sides of the spectrum to return. 'default' is one-sided for real
+        data and two-sided for complex data. 'onesided' forces the return of a
+        one-sided spectrum, while 'twosided' forces two-sided.
 """))
 
 
@@ -676,10 +674,10 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
         'linear' calls `.detrend_linear`.
 
     scale_by_freq : bool, optional
-        Specifies whether the resulting density values should be scaled
-        by the scaling frequency, which gives density in units of Hz^-1.
-        This allows for integration over the returned frequency values.
-        The default is True for MATLAB compatibility.
+        Whether the resulting density values should be scaled by the scaling
+        frequency, which gives density in units of Hz^-1.  This allows for
+        integration over the returned frequency values.  The default is True
+        for MATLAB compatibility.
 """))
 
 
diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
@@ -868,18 +868,16 @@ def _h_arrows(self, length):
     start of the barb that many points away from grid point.
 
 barbcolor : color or color sequence
-    Specifies the color of all parts of the barb except for the flags.  This
-    parameter is analogous to the *edgecolor* parameter for polygons,
-    which can be used instead. However this parameter will override
-    facecolor.
+    The color of all parts of the barb except for the flags.  This parameter
+    is analogous to the *edgecolor* parameter for polygons, which can be used
+    instead. However this parameter will override facecolor.
 
 flagcolor : color or color sequence
-    Specifies the color of any flags on the barb.  This parameter is
-    analogous to the *facecolor* parameter for polygons, which can be
-    used instead. However, this parameter will override facecolor.  If
-    this is not set (and *C* has not either) then *flagcolor* will be
-    set to match *barbcolor* so that the barb has a uniform color. If
-    *C* has been set, *flagcolor* has no effect.
+    The color of any flags on the barb.  This parameter is analogous to the
+    *facecolor* parameter for polygons, which can be used instead. However,
+    this parameter will override facecolor.  If this is not set (and *C* has
+    not either) then *flagcolor* will be set to match *barbcolor* so that the
+    barb has a uniform color. If *C* has been set, *flagcolor* has no effect.
 
 sizes : dict, optional
     A dictionary of coefficients specifying the ratio of a given
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -46,11 +46,11 @@
 The ``plot`` directive supports the following options:
 
     format : {'python', 'doctest'}
-        Specify the format of the input
+        The format of the input.
 
     include-source : bool
         Whether to display the source code. The default can be changed
-        using the `plot_include_source` variable in conf.py
+        using the `plot_include_source` variable in :file:`conf.py`.
 
     encoding : str
         If this source file is in a non-UTF8 or non-ASCII encoding, the
diff --git a/lib/matplotlib/transforms.py b/lib/matplotlib/transforms.py
@@ -2907,7 +2907,7 @@ def offset_copy(trans, fig=None, x=0.0, y=0.0, units='inches'):
     fig : :class:`~matplotlib.figure.Figure`, optional, default: None
         Current figure. It can be None if *units* are 'dots'.
     x, y : float, optional, default: 0.0
-        Specifies the offset to apply.
+        The offset to apply.
     units : {'inches', 'points', 'dots'}, optional
         Units of the offset.
 
