improve Axes.pie docstring

timhoffm · timhoffm · commit 4ac0dd1b379a · 2018-01-04T14:59:00.000+01:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -2517,30 +2517,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
@@ -2550,9 +2552,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.
@@ -2572,7 +2573,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``.
@@ -2581,8 +2582,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.
@@ -2596,11 +2597,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
