add reuse warning about buffered iterators

[brahn]

The scaladocs for Iterators has a very useful warning on the method buffered:

Reuse: After calling this method, one should discard the iterator it was called on,
and use only the iterator that was returned. Using the old iterator is undefined,
subject to change, and may result in changes to the new iterator as well.

This PR adds that warning (along with some explanatory text) to the corresponding discussion on http://docs.scala-lang.org/overviews/collections/iterators.html#buffered-iterators

(I got bitten by looking at the latter without seeing the former.)

[SethTisue]

a great many methods on Iterator have this issue; buffered isn't really special in this regard. what do you think about taking what you've done here and making the warning more general...?

[som-snytt]

in #551 I just reiterate, "don't re-use the original iterator", which is the theme of most of the page.

I also place an ad for Iterator.single(head) ++ rest. It makes me wonder if BufferedIterator.toIterator should do that; except that it doesn't have much overhead, which is another point I added.

[SethTisue]

superseded by #551. thanks @brahn for calling it to the community's attention