Incorporate @raphlinus' container cheat sheet into the std::collections module docs #42412
Description
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)
Metadata
Metadata
Assignees
Labels
Type
Projects
Milestone
Relationships
Development
No branches or pull requests
Participants
Activity
nagisa commentedon Jun 3, 2017
This is documenting (read: semi-stabilises) internal implementation details which could change at any time.
leonardo-m commentedon Jun 3, 2017
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 commentedon Jun 3, 2017
Well I’m all fine with it, as long as people do not
transmutethe types/do some other black magic and then come over crying because it was “documented”.leonardo-m commentedon Jun 3, 2017
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 commentedon Aug 30, 2017
@rust-lang/libs, should we do this or not? I share @nagisa 's concerns.
Kixunil commentedon Nov 20, 2017
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 commentedon Dec 28, 2018
The current version needs a touch of updating before inclusion though.
pickfire commentedon Aug 29, 2020
This is also available in https://cheats.rs/#standard-library-types
pickfire commentedon Aug 29, 2020
@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 commentedon Aug 29, 2020
we normally don't label issues for hacktoberfest :P
the8472 commentedon Aug 29, 2020
std already has several pieces of documentation that exempt themselves from stability guarantees. E.g.
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 commentedon Mar 10, 2021
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 commentedon Mar 10, 2021
@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 commentedon Mar 10, 2021
@Kixunil this started over at the book. From the issue text:
Kixunil commentedon Mar 11, 2021
OK then, adding "Write a book about professional Rust development" to my infinite TODO list. :)