Document that .iter() has an element type of &T

[Wilfred]

The docs for Vec::iter show the following type:

fn iter(&self) -> Iter<T>

As a result, I was puzzled that the following doesn't work:

let bar: Vec<&str> = vec!["a", "b", "c", "b"].iter().collect();

It turns out that that Iter implements an iterator with element type &T. On the Iter docs page we see type Item = &'a T but it's easy to overlook.

I think it would be worth adding a line to Vec::iter's documentation to say:

Iterator element type is &T.

This is the approach taken in itertools docs (example) and I think it helps significantly.

[steveklabnik]

I'm generally not a fan, as text is hard to track with changes. I'd rather see rustdoc grow support for something like this if if's truly useful. I'm not sure how common this misunderstanding is.

[bluss]

I'm a fan of this. I think the iterator element type is only obvious when you already know rust quite well, and it answers one of the single most important questions missing from the function signature.

[Gankra]

Ideally all these interfaces should just say -> impl Iterator<&T> or
whatever that future syntax is.

On Sun, May 31, 2015 at 11:33 AM, bluss notifications@github.com wrote:

I'm a fan of this. I think the iterator element type is only obvious when
you already know rust quite well, and it answers one of the single most
important questions missing from the function signature.

—
Reply to this email directly or view it on GitHub
#25928 (comment).

[bluss]

Yes but that's far future right now.

I'm wondering what we are going to do about multiple traits. I mean, -> impl Iterator<&T> doesn't describe all we need from it, we need something like -> impl DoubleEndedIterator<Item=&T> + ExactSizeIterator + Clone.

[thenewwazoo]

Raising this from the dead to say that this just bit me, as a relative newbie to Rust (e.g. "why do I have to dereference twice in .filter?)

[QuietMisdreavus]

I've started #45039 to work on this.