Specs

[Brian Goetz]

> I agree that people need some advice on the fine points of using
> parallel to avoid unexpected slowdowns, but Javadocs are not
> an ideal place to describe possibly-transient facts about
> crummy performance in various cases. (They belong in the bug database! :-)

I think @implNote is a fine place to put possibly-transient details that 
users might use at their own risk?  Especially if we can frame it as 
"things that work" rather than "things that don't."  For example, in 
limit, we could @implNote: parallel operations on ordered streams may 
require O(limit) buffering.  But if the stream is SIZED and SUBSIZED, 
don't worry, be happy.

The idea here is: you warn users of possible things to watch out for, 
and identify conditions under which they are safe.  Ideally that set of 
conditions would grow over time, making it less likely such transient 
information gets stale.