Add some Vec <-> VecDeque documentation

[scottmcm]

These are more than just .into_iter().collect(), so talk about some of their nuances.

For VecDeque -> Vec I'm trying to intentionally not write a guarantee for people making their own Vecs, since the rules are more complicated than I think we want to commit to forever.

The "Vec -> VecDeque doesn't reallocate" guarantee seems reasonable, though. (And I'm intentionally ambiguous about when it's O(1) instead of O(n).)

[rust-highfive]

r? @sfackler

(rust_highfive has picked a reviewer for you, use r? to override)

[Centril]

Some proof-reading.

[czipperz]

What's the precedent for documenting trait impl blocks vs trait functions? My understanding is the former is easier to see on the docs webpage because functions are minimized.

[scottmcm]

@czipperz Well, @Mark-Simulacrumsaid on discord,

I'd go with method since it's somewhat clearer imo what you're specifically documenting, though for From it doesn't matter since there's just the one method

(I'm happy to do whatever here.)

[czipperz]

Looking through other parts of std, it seems like documenting the method is standard. Also, when you override the documentation it automatically expands in rustdoc: try https://doc.rust-lang.org/nightly/std/net/enum.SocketAddr.html for From<(I, u16)>

[Mark-Simulacrum]

In rust-lang/rust a loose grep appears to suggest 96 cases of documentation on trait impls (among ~20,000 trait impls) so I would say the clear preference is definitely for the method.

[sfackler]

What's the motivation for spending so much time worrying about reallocation here?

[czipperz]

I think there is a few open issues where people want to know about our allocation strategy for various From impls. In other words, people want to know so they are being explicit about it.

[scottmcm]

Basically, the only thing interesting about these two From impls is that they can (sometimes) avoid allocations compared to .into_iter().collect(). So I want to write an example that shows the lack of reallocation, but I also want to write it in such a way that it's a situation where we'd be ok committing to the lack of reallocation. So I want to make an example that doesn't do things like "well, I happen to know that right now it doesn't reallocate if I with_capacity(8) and don't use all the capacity", because I don't want to write text elaborating why those conditions work.

I agree this example is far more complicated than most, though, so would be happy to change it.

[sfackler]

I don't know if an example is really helpful at all here, if we don't actually want to guarantee anything.

[scottmcm]

@sfackler Ok, I removed the example from here.

[czipperz]

Should we be including links to VecDeque from Vec and Vec from VecDeque? I think this makes sense because it increases the navigability of the source code. But the docs will already link to them for us as part of the signature. I would still go on the side of links.

[czipperz]

So converting to VecDeque can reallocate and to Vec can shift elements around

[sfackler]

@bors r+

[bors]

📌 Commit 0150448 has been approved by sfackler