Incorporate @raphlinus' container cheat sheet into the std::collections module docs

[carols10cents]

The suggestion to incorporate @raphlinus' container cheat sheet was made by @leonardo-m over on rust-lang/book#741, and @steveklabnik and I agree that it's a better fit for the API docs rather than the book (since the book is aiming to be a narrative intro to Rust, not a comprehensive reference).

Raph has noted that the cheat sheet is Copyright 2017 Google Inc., released under Creative Commons BY, so I don't think that should be a problem for us to incorporate as long as we note those things (but IANAL)

[nagisa]

This is documenting (read: semi-stabilises) internal implementation details which could change at any time.

[leonardo-m]

Note that cheat sheet contains some small mistakes and imprecisions.

Regarding the problem of documenting internal implementation details, when those details change, the sheet should be updated. The purpose of those images is to help a Rust programmer know what she or he is using. If you don't know those things you can't program well in Rust.

[nagisa]

Well I’m all fine with it, as long as people do not transmute the types/do some other black magic and then come over crying because it was “documented”.

[leonardo-m]

But I agree it's surely a risk, even if you write very well in the page that those images are not meant to be used that way, etc.

[steveklabnik]

@rust-lang/libs, should we do this or not? I share @nagisa 's concerns.

[Kixunil]

There was a question regarding references on Reddit recently. I believe this (or similar) visualization would be very helpful for beginners.

There should be a big warning about not transmuting stuff and not relying on that layout. If someone will ignore that, he will probably ignore many other things.

[huhlig]

The current version needs a touch of updating before inclusion though.

[pickfire]

This is also available in https://cheats.rs/#standard-library-types

[pickfire]

@Dylan-DPC Maybe we can label hacktoberfest?

cc @rust-lang/rustdoc @jyn514 (I don't know if I CCed the correct team)

[Dylan-DPC-zz]

we normally don't label issues for hacktoberfest :P

[the8472]

std already has several pieces of documentation that exempt themselves from stability guarantees. E.g.

• https://doc.rust-lang.org/std/net/struct.Ipv4Addr.html#method.is_reserved
• https://doc.rust-lang.org/std/fs/fn.copy.html#platform-specific-behavior

Maybe it would make sense to have a standard marker for these kinds of things. E.g. w3c specs oven have non-normative sections. Similarly java docs have annotations for implementation notes that are subject to change

[joshtriplett]

We reviewed this in today's @rust-lang/libs meeting.

This is a great piece of documentation, but it's focused on data structure internals, not on user-visible properties or uses. As a result, we don't think this is a good fit for user-focused documentation.

It might make sense to link to it from documentation about developing the standard library, but we don't want to add this to the collections documentation.

[Kixunil]

@joshtriplett perhaps the Book would be a better place? I believe that in systems language knowing about performance characteristics is just as important as knowing the API. E.g. why not just use Option<Arc<Mutex<Vec<T>>>> everywhere?

[carols10cents]

@Kixunil this started over at the book. From the issue text:

The suggestion to incorporate @raphlinus' container cheat sheet was made by @leonardo-m over on rust-lang/book#741, and @steveklabnik and I agree that it's a better fit for the API docs rather than the book (since the book is aiming to be a narrative intro to Rust, not a comprehensive reference).

[Kixunil]

OK then, adding "Write a book about professional Rust development" to my infinite TODO list. :)