Update FusedIterator docs to reflect current behavior

[asquared31415]

The current implementation makes no guarantees. In the best cases it's only a memory overhead, in the worst it's incorrect.

This is technically probably a breaking change in docs, but the trait has had no such guarantees in its implementation since it's creation.

[rustbot]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[rust-highfive]

r? @scottmcm

(rust-highfive has picked a reviewer for you, use r? to override)

[scottmcm]

I don't think it's helpful to rewrite all the docs to say "might" just because they're not unsafe traits. See the recent conversation in https://internals.rust-lang.org/t/documentation-must-vs-should/16967?u=scottmcm.

An iterator that claims to be FusedIterator when it doesn't actually fuse is subject to "garbage in garbage out" logical incorrectness, just not to UB. This is the same as, for example, how Ord doesn't say "might be an order". It says "Implementations must be consistent with [...]" because that's a MUST for correctness.

So I'm not willing to change these docs to "may continue to". That makes the trait completely useless, because that's the same as any Iterator.

@rustbot author