Repository: rust-itertools/itertools (language: rust)

Issue:
Interleave doc should explains how it is different from `std::iter::zip`
When reading the documentation of [interleave](https://docs.rs/itertools/0.9.0/itertools/fn.interleave.html) I wasn't able to understand what is the difference with [`std::iter::zip()`](https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.zip), and why/when should one be preferred to the other.


Discussion / hints:
In fact, [`interleave`] has much more in common with [`chain`] than with [`zip`]. From the example in [`Itertools::interleave`] it becomes clear that
1. `interleave`'s `Item` is the same as the input iterators's `Item`s.
2. `interleave` tries to yield elements from different iterators every time (until one of them is run out of elements)

[`interleave`]: https://docs.rs/itertools/0.9.0/itertools/fn.interleave.html
[`chain`]: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.chain
[`zip`]: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.zip
[`Itertools::interleave`]: https://docs.rs/itertools/0.9.0/itertools/trait.Itertools.html#method.interleave
I think I understand now:

- `zip` takes one element from each iterator, and returns a tuple each time `next()` is called
- `interleave` pick one element from one iterator, then one element from the next iterator, and so on, until all iterators are exausted
- `chain` pick all the elements from the first iterator one by one, until the iterator is exhausted, then do the same with the next iterator, and so on.

Which means that:

- `[1,2,3].iter().zip([4,5,6])` yields `(1,4), (2,5), (3,6)`
- `[1,2,3].iter().interleave([4,5,6])` yields `1,4,2,5,3,6`
- `[1,2,3].iter().chain([4,5,6])` yields `1,2,3,4,5,6`

Did I got this right?
Yes, that's right

Fix patch:
diff --git a/src/adaptors/mod.rs b/src/adaptors/mod.rs
index f1f20489d..038fa6951 100644
--- a/src/adaptors/mod.rs
+++ b/src/adaptors/mod.rs
@@ -31,13 +31,7 @@ pub struct Interleave<I, J> {
 ///
 /// `IntoIterator` enabled version of `i.interleave(j)`.
 ///
-/// ```
-/// use itertools::interleave;
-///
-/// for elt in interleave(&[1, 2, 3], &[2, 3, 4]) {
-///     /* loop body */
-/// }
-/// ```
+/// See [`.interleave()`](trait.Itertools.html#method.interleave) for more information.
 pub fn interleave<I, J>(i: I, j: J) -> Interleave<<I as IntoIterator>::IntoIter, <J as IntoIterator>::IntoIter>
     where I: IntoIterator,
           J: IntoIterator<Item = I::Item>


Test patch: