Clarify the uses of whiskers float parameter.

[Carreau]

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:

"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.

---

Improvement thanks to @emilienschultz, but I already had a matplotlib clone and a dev install, so it was faster for me to fix it.

[codecov-io]

Current coverage is 62.12% (diff: 100%)

Merging #7753 into master will not change coverage

@@             master      #7753   diff @@
==========================================
  Files           174        174          
  Lines         56028      56028          
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
  Hits          34805      34805          
  Misses        21223      21223          
  Partials          0          0          

Powered by Codecov. Last update 1fa4dd7...a7b04b1

[tacaswell]

"will be at last data point less than Q3 + whis*IQR."?

[Carreau]

Changed to your wording.

[Carreau]

(in both docstrings)

[phobson]

I think this is headed in the right direction. I would recommend:

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.

[phobson]

FWIW, wikipedia currently explains this as:

the lowest datum still within 1.5 IQR of the lower quartile, and the highest datum still within 1.5 IQR of the upper quartile.

I think that would work as well (with attribution)

[Carreau]

@phobson pushed with your first phrasing. I find it clearer than the wikipedia one.

[phobson]

Thanks!

[NelleV]

The failure is unrelated to the patch, so I'm merging.
Thanks @Carreau !

[QuLogic]

Backported to v2.0.x as f12fa6e.

[Carreau]

Backported to v2.0.x as f12fa6e.

Thanks.

Just a question: Isn't that a bit overkill for a patch release ? For a 2.x I would have understood, even if I believe this would not fit a backport to a minor in IPython. Or I'm misinterpreting the numbering of matplotlib.

[QuLogic]

I'm just going by the milestone, but documentation corrections are generally safe to backport.

[Carreau]

I'm just going by the milestone,

Yes, I understand that, and thanks for doing it.

but documentation corrections are generally safe to backport.

That's not a question of "safety", it's also a question of maintainer time and message to the community.
If backport everything and spend 1h backporting 10 PRs then that's 1h less of actual code review.
Plus it's not helping to convey a clear message to the community as to what will be better in 2.1.

Typically #7766 was deprecation warnings, was it really worth backporting ? Or is #7913 (quiver docs and example), which for me just an addition (and a carrot to upgrade on 2.1) if it had been only on 2.1

I just don't want to guys to burnout by doing too much.