Merge pull request matplotlib#7753 from Carreau/improve-whiskers-docstrings

Clarify the uses of whiskers float parameter.

Author: NelleV

lib/matplotlib/axes/_axes.py

@@ -3128,9 +3128,12 @@ 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 beyond the
+            first and third quartiles. In other words, where IQR is the
+            interquartile range (`Q3-Q1`), the upper whisker will extend to
+            last datum less than `Q3 + whis*IQR`). Similarly, the lower whisker
+            will extend to the first datum greater than `Q1 - 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

lib/matplotlib/cbook.py

@@ -1872,9 +1872,12 @@ 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 beyond the
+        first and third quartiles. In other words, where IQR is the
+        interquartile range (`Q3-Q1`), the upper whisker will extend to last
+        datum less than `Q3 + whis*IQR`). Similarly, the lower whisker will
+        extend to the first datum greater than `Q1 - 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`