iterate: document a possible panic

[Philippe-Cholet]

Resolves #600. See #600 (comment) for why I don't see an alternative.

[phimuemue]

I approve this, because having the docs is better than not having them.

But isn't the interesting part here that the "next next" value is computed in next? And: Doesn't successors potentially suffer the same problem (albeit able to circumvent it using None)? (see https://doc.rust-lang.org/beta/src/core/iter/sources/successors.rs.html#48)

[Philippe-Cholet]

Without Clone-able values, iterate and successors are forced to compute it ahead-of-time while we still have access to the value, it's the trade-off: not cloned but ahead-of-time computation. But being able to return None in successors' closure seems a better API decision to me.

EDIT: Not being able to stop the iterator with None kinda suppose it can continue forever (Iterate::size_hint explicitly says it).

The working example of iterate seems more like a successors example to me.
iterate(1, |n| (n + 1) % 3) would be appropriate to me.

... It lead me to change the working example to better describe iterate vs successors.
It could be something different than basically (1..=3).cycle() though.