Mention iter::zip in the documentation for Iterator::zip

[scottmcm]

Now that iter::zip is stable (#91881), we can mention it in the documentation of other stable methods.

It would thus be nice to mention it in the documentation for Iterator::zip, both to help people discover it and to help them decide when to use which.

It already has a s1.iter().zip(s2); example talking about IntoIterator, so maybe it would make sense to mention iter::zip in terms of when you want that on both sides, as zip(s1, s2).

If you start working on this, please comment @rustbot claim to help avoid duplicate effort.

[cameron1024]

@rustbot claim

[cameron1024]

I've just had a look through the PRs, am I right in thinking the purpose of this is just a nicer syntax for zipping iterators? Should the docs suggest preferring zip(as, bs) over as.into_iter().zip(bs), or are there reasons why you'd prefer one over the other?

[scottmcm]

#82917 has the reasoning why iter::zip was added.

I think it depends how similar the sides are. If the call chain in them is similar in structure, and particularly when it's things that are IntoIterator but not Iterator (like arrays or reference-to-vector) then I think the function is better. But if you have a long chain (maybe with a big map closure) that's then zipped with something simple, the method could be easier to read.

TBH, I tended to write Iterator::zip(a.iter(), b.iter()) anyway (because I prefer function-like form for symmetric things) so I'd probably use the function most of the time. But I don't know how pervasive that behaviour is.