Clarify the uses of whiskers float parameter.

Carreau · Carreau · commit 8e96d30ffe50 · 2017-01-06T16:14:28.000+01:00
It is not clear (at least to a couple of non-native English speakers)
that the whiskers extend to the last data point. More precisely:

&gt; "If it's 1.5 times Q3-Q1 it should be symmetric"

The code does seem to limit the whisker to the last data point, and that
correspond to one of the usage of whiskers described by Wikipedia.

So fix docstrings.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -3126,9 +3126,11 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
             everything is drawn horizontally.
 
         whis : float, sequence, or string (default = 1.5)
-            As a float, determines the reach of the whiskers past the
-            first and third quartiles (e.g., Q3 + whis*IQR,
-            IQR = interquartile range, Q3-Q1). Beyond the whiskers, data
+            As a float, determines the reach of the whiskers to the first
+            (resp. last) datum past the first (resp. third) quartiles
+            (e.g., Q3 + whis*IQR, IQR = interquartile range, Q3-Q1, whisker
+            will be at last data point less than Q3 + whis*IQR).
+            Beyond the whiskers, data
             are considered outliers and are plotted as individual
             points. Set this to an unreasonably high value to force the
             whiskers to show the min and max values. Alternatively, set
diff --git a/lib/matplotlib/cbook.py b/lib/matplotlib/cbook.py
@@ -1872,9 +1872,11 @@ def boxplot_stats(X, whis=1.5, bootstrap=None, labels=None,
         fewer dimensions.
 
     whis : float, string, or sequence (default = 1.5)
-        As a float, determines the reach of the whiskers past the first
-        and third quartiles (e.g., Q3 + whis*IQR, QR = interquartile
-        range, Q3-Q1). Beyond the whiskers, data are considered outliers
+        As a float, determines the reach of the whiskers to the first (resp.
+        last) datum past the first (resp. third) quartiles 
+        (e.g., Q3 + whis*IQR, IQR = interquartile range, Q3-Q1, whisker will
+        be at last data point less than Q3 + whis*IQR).
+        Beyond the whiskers, data are considered outliers
         and are plotted as individual points. This can be set this to an
         ascending sequence of percentile (e.g., [5, 95]) to set the
         whiskers at specific percentiles of the data. Finally, `whis`
