Backport PR #10150: Docstring updates for Axes.fill and Axes.pie

jklymak · MeeseeksDev[bot] · commit 67d1ec661a5a · 2018-01-05T22:56:05.000Z
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -2462,30 +2462,32 @@ def pie(self, x, explode=None, labels=None, colors=None,
             startangle=None, radius=None, counterclock=True,
             wedgeprops=None, textprops=None, center=(0, 0),
             frame=False, rotatelabels=False):
-        r"""
+        """
         Plot a pie chart.
 
-        Make a pie chart of array *x*.  The fractional area of each
-        wedge is given by ``x/sum(x)``.  If ``sum(x) <= 1``, then the
-        values of x give the fractional area directly and the array
-        will not be normalized.  The wedges are plotted
-        counterclockwise, by default starting from the x-axis.
+        Make a pie chart of array *x*.  The fractional area of each wedge is
+        given by ``x/sum(x)``.  If ``sum(x) < 1``, then the values of *x* give
+        the fractional area directly and the array will not be normalized. The
+        resulting pie will have an empty wedge of size ``1 - sum(x)``.
+
+        The wedges are plotted counterclockwise, by default starting from the
+        x-axis.
 
         Parameters
         ----------
         x : array-like
-            The input array used to make the pie chart.
+            The wedge sizes.
 
         explode : array-like, optional, default: None
-            If not *None*, is a ``len(x)`` array which specifies the
-            fraction of the radius with which to offset each wedge.
+            If not *None*, is a ``len(x)`` array which specifies the fraction
+            of the radius with which to offset each wedge.
 
         labels : list, optional, default: None
             A sequence of strings providing the labels for each wedge
 
         colors : array-like, optional, default: None
             A sequence of matplotlib color args through which the pie chart
-            will cycle.  If `None`, will use the colors in the currently
+            will cycle.  If *None*, will use the colors in the currently
             active cycle.
 
         autopct : None (default), string, or function, optional
@@ -2495,9 +2497,8 @@ def pie(self, x, explode=None, labels=None, colors=None,
             If it is a function, it will be called.
 
         pctdistance : float, optional, default: 0.6
-            The ratio between the center of each pie slice and the
-            start of the text generated by *autopct*.  Ignored if
-            *autopct* is *None*.
+            The ratio between the center of each pie slice and the start of
+            the text generated by *autopct*.  Ignored if *autopct* is *None*.
 
         shadow : bool, optional, default: False
             Draw a shadow beneath the pie.
@@ -2517,7 +2518,7 @@ def pie(self, x, explode=None, labels=None, colors=None,
 
         wedgeprops : dict, optional, default: None
             Dict of arguments passed to the wedge objects making the pie.
-            For example, you can pass in``wedgeprops = {'linewidth': 3}``
+            For example, you can pass in ``wedgeprops = {'linewidth': 3}``
             to set the width of the wedge border lines equal to 3.
             For more details, look at the doc/arguments of the wedge object.
             By default ``clip_on=False``.
@@ -2526,8 +2527,8 @@ def pie(self, x, explode=None, labels=None, colors=None,
             Dict of arguments to pass to the text objects.
 
         center :  list of float, optional, default: (0, 0)
-            Center position of the chart. Takes value (0, 0) or is a
-            sequence of 2 scalars.
+            Center position of the chart. Takes value (0, 0) or is a sequence
+            of 2 scalars.
 
         frame : bool, optional, default: False
             Plot axes frame with the chart if true.
@@ -2541,11 +2542,11 @@ def pie(self, x, explode=None, labels=None, colors=None,
             A sequence of :class:`matplotlib.patches.Wedge` instances
 
         texts : list
-            A is a list of the label :class:`matplotlib.text.Text` instances.
+            A list of the label :class:`matplotlib.text.Text` instances.
 
         autotexts : list
-            A is a list of :class:`~matplotlib.text.Text` instances for the
-            numeric labels. Is returned only if parameter *autopct* is
+            A list of :class:`~matplotlib.text.Text` instances for the numeric
+            labels. This will only be returned if the parameter *autopct* is
             not *None*.
 
         Notes
@@ -4648,34 +4649,35 @@ def fill(self, *args, **kwargs):
 
         Parameters
         ----------
-        args : a variable length argument
-            It allowing for multiple
-            *x*, *y* pairs with an optional color format string; see
-            :func:`~matplotlib.pyplot.plot` for details on the argument
-            parsing.  For example, each of the following is legal::
+        args : sequence of x, y, [color]
+            Each polygon is defined by the lists of *x* and *y* positions of
+            its nodes, optionally followed by by a *color* specifier. See
+            :mod:`matplotlib.colors` for supported color specifiers. The
+            standard color cycle is used for polygons without a color
+            specifier.
 
-                ax.fill(x, y)
-                ax.fill(x, y, "b")
-                ax.fill(x, y, "b", x, y, "r")
+            You can plot multiple polygons by providing multiple *x*, *y*,
+            *[color]* groups.
 
-            An arbitrary number of *x*, *y*, *color* groups can be specified::
-            ax.fill(x1, y1, 'g', x2, y2, 'r')
+            For example, each of the following is legal::
+
+                ax.fill(x, y)                    # a polygon with default color
+                ax.fill(x, y, "b")               # a blue polygon
+                ax.fill(x, y, x2, y2)            # two polygons
+                ax.fill(x, y, "b", x2, y2, "r")  # a blue and a red polygon
 
         Returns
         -------
-        a list of :class:`~matplotlib.patches.Patch`
+        a list of :class:`~matplotlib.patches.Polygon`
 
         Other Parameters
         ----------------
         **kwargs : :class:`~matplotlib.patches.Polygon` properties
 
         Notes
         -----
-        The same color strings that :func:`~matplotlib.pyplot.plot`
-        supports are supported by the fill format string.
-
-        If you would like to fill below a curve, e.g., shade a region
-        between 0 and *y* along *x*, use :meth:`fill_between`
+        Use :meth:`fill_between` if you would like to fill the region between
+        two curves.
 
 
         """
