On 6/3/15 9:21 AM, Paul Sandoz wrote:
I had prepared an alternative rendition stashed away just in case this came up :-)I still want to retain a punchy short first paragraph. What do you think about the following? /** - * Returns a stream consisting of the longest prefix of elements taken from - * this stream that match the given predicate. + * Returns a stream consisting of elements taken from this stream that match + * the given predicate.
Well, I'm sorry to say, this reminds me of that old tech support joke about the answer that is technically true but completely useless. :-)
It's not incorrect, of course, but it's almost indistinguishable from the first sentence of Stream.filter().
People who know what "takeWhile" means will raise an eyebrow at this, go read the rest of the doc, and go "ohhh, yeah there's this complication with unordered streams." People who are trying to learn the system will go "Huh?"
I agree on the need for a punchy first sentence since that's what goes into the Method Summary. The difficulty is making something sufficiently general that it covers all the cases, while not making it so vague as to be useless.
Sorry, but I don't have any better suggestions at the moment. I might be able to come up with something in the next few days... but don't let this hold you up if you need to press forward.
s'marks
