Change:
/// } /// ``` /// <ins> /// `HashMap` also implements an [`Entry API`](#method.entry), which allows /// for more complex methods of getting, setting, updating and removing keys and /// their values: /// /// ``` /// use std::collections::HashMap; /// /// // type inference lets us omit an explicit type signature (which /// // would be `HashMap<&str, u8>` in this example). /// let mut player_stats = HashMap::new(); /// /// fn random_stat_buff() -> u8 { ///   // could actually return some random value here - let's just return ///   // some fixed value for now ///   42 /// } /// /// // insert a key only if it doesn't already exist /// player_stats.entry("health").or_insert(100); /// /// // insert a key using a function that provides a new value only if it /// // doesn't already exist /// player_stats.entry("defence").or_insert_with(random_stat_buff); /// /// // update a key, guarding against the key possibly not being set /// let stat = player_stats.entry("attack").or_insert(100); /// *stat += random_stat_buff(); /// ``` /// </ins> /// The easiest way to use `HashMap` with a custom type as key is to derive `Eq` and `Hash`. /// We must also derive `PartialEq`. ///

Discussion:
Part of This will probably need to be tackled in pieces.
What needs to be done here? Just cleanup?
Yeah, overall, these bugs are like "Steve's eye of Sauron will check the entire standard library at least once." I haven't actually looked at collections' docs lately, but sample things are like: sure everything is following doc conventions sure everything has examples sure everything is explained well I don't have any specific goals yet.
As discussed on , I'll also try to help out by adding some more examples for using the entry API to update/modify a et al.
Some things I've noticed that are relevant to this: The use of vs for constructors The use of unconventional first lines for iterator-returning methods, e.g. vs The use of both "element" and "value"
The blurb on complex keys in the map methods isn't clear that it's talking about complex keys: It's the key that is not updated. The value is updated. The linked module-level documentation makes this clear.
I've raised the above (long overdue!) PR, which you've been as quick as lightning and already looked at! Are there any other particular parts of the collection APIs that need attention in terms of examples, etc. that I can have a look at? Would be good to perhaps put together a checklist of stuff that needs some work so we can pick them off in bits.
In general, every single method and function should have an example, as a baseline. I haven't dug into the collections docs in a while, so I don't have a ton of details about specifics right now, but that's at least the baseline.
Okay awesome, I might start going through some of them and will add the ones I've checked back here for reference. :+1:
That'd be spectacular.
Okay, have been through the collection docs and here's the ones that need checking (ie. they actually have methods/functions and are not just trait implementations). I'm going to try and raise PRs separately for each of these things to add at least the missing examples for now. Top level structs: -PR -PR -PR -PR Collection specific structs:
Don't worry about unstable things. It's not worth the time, since they are unstable.

I plan on going back through after each release and writing docs for things as they become stable; it's just too early in my overall pass through to worry about yet. On Jan 20, 2016, 16:53 -0500, Nathan , wrote:
All done.
I would like to reopen this issue since I think the documentation of the  still leaves a lot to be desired. In particular, it lacks enough rigor to make informed decisions about using the collections and their methods. In my opinion, and independently of how repetitive it is, the documentation of each method should have the following "fields": Algorithmic complexity: with big O in terms of the relevant operations (which can be multiple: memory allocations in terms of N, copies in terms of M, stating what N and M are, swaps, comparisons, hashing...), with exact number of operations when guaranteed (performs exactly N moves, performs exactly N swaps, ...), with an explanation of what amortized/expected complexity means for that particular operation, covering what happens in the amortized case and in the worst case. Memory complexity: does it use O(1) stack space? Is it recursive and it uses O(logN) stack space? Does it allocate memory using the system allocator? If so how much? Something like: "Requires O(1) stack space and allocates O(N) memory where N is x". Effects: What are the effects of the operation? Example: : before: , , after: , (amortized case) or (worst case). Example: : before: , after: . Panics: When is an operation supposed to panic? Example: panics if OOM. Example: never panics. For a source of inspiration, the C++ standard is exemplary at documented all of these things. I really think that being more thorough with the documentation will help both find and fix bugs in the documentation and make the std library way better. So IMO what remains to be done is: [ ] Achieve consensus on how to document the methods of the std library algorithms and collections. [ ] Explore if there is an easy way to reuse some documentation bits (e.g. OOM panics, never panics, explanation for amortized / expected complexity). [ ] Go (again) through all methods and document them rigorously.

Another thing I've found is that not all collections are mentioned in the main collections page (e.g. ). [ ] Make sure that all collections are mentioned in all relevant sections of the main page (when to use, performance, ...). Some examples of the current state of things: doesn't even mention that insertions are O(1). Yes, this information might be in some other place of the documentation, but if I google for "Rust HashMap insert" I land there and would like to see all relevant information right away. requires amortized O(1) stack memory but in the worst case it requires memory and moves (where is an implementation defined growth-factor). This information should be explicit in the method documentation.  complexity is O(NlogN) in the number of elements, but it mentions that it allocates approximately "2n" elements. This is not too bad but "approximately" is too vague for my taste. Does that mean at worst ? In particular, stable sorting algorithms like merge sort require 1/2N, and GrailSort requires O(1), so this leaves me wondering whether 2N is actually a bug in the documentation. If the rust std library would have an unstable sorting algorithms (which I could not find) implemented with something quicksort-based like intro-sort, it should say that it is "in place", that is, doesn't allocate extra memory, but uses O(logN) stack space. EDIT: I ran into this when I wanted to see if it made sense to use for my application. I googled "Rust HashSet insert" and found the method, but had no idea what the complexity and memory allocations of the method were. Then I went to the collections main page, but again did not found this information... I think we can do better.
Good points. Since this issue is getting old, I propose to you to reopen it with your message directly. (and please cc me in it when it's done).