Weaken guarantee around advancing underlying iterators in zip

the8472 · the8472 · commit 2ff677dcbe22 · 2021-08-11T21:09:00.000+02:00
The current guarantee is too strong as it would prevent adapters
from exploiting knowledge about the iterator length and using counted
loops for example because they would stop calling `next()` before
it ever returned `None`. Additionally several nested zip iterators
already fail to uphold this.

This doesn't remove any of the specialization code that tries
(and sometimes fails) to uphold the guarantee for `next()`
because removing it would also affect `next_back()`
in more surprising ways.
diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs
@@ -457,8 +457,10 @@ pub trait Iterator {
     /// In other words, it zips two iterators together, into a single one.
     ///
     /// If either iterator returns [`None`], [`next`] from the zipped iterator
-    /// will return [`None`]. If the first iterator returns [`None`], `zip` will
-    /// short-circuit and `next` will not be called on the second iterator.
+    /// will return [`None`].
+    /// If the zipped iterator has no more elements to return then each further attempt to advance
+    /// it will first try to advance the first iterator at most one time and if it still yielded an item
+    /// try to advance the second iterator at most one time.
     ///
     /// # Examples
     ///
