Unclear doc on iterator.by_ref()

[Yuri6037]

Today, I just got a huge problem internally in one of my crate. The bug is that the call to iterator.by_ref mutates/advances the iterator itself internally and that caused one of my software dependent on that carate to fail with an internal weird panic.

On the following documentation link: https://doc.rust-lang.org/stable/std/iter/trait.Iterator.html#method.by_ref the behavior of the function is not very clear.

The doc currently reads:

Borrows an iterator, rather than consuming it.

This is useful to allow applying iterator adapters while still retaining ownership of the original iterator.

From this text it's not clear that using this function still mutates/advances the internal iterator, so calling count for example is still gonna put the iterator to the end and will break all subsequent calls, essentially ending in weird cases where somehow the number of items is 1 but the later call to last().unwrap() panics!

[zirconium-n]

While you might be right this text is not clear (which I do not agree), the example clearly shows that the internal iterator still advances.