API Docs: collections

[steveklabnik]

Part of #29329

http://doc.rust-lang.org/std/collections/

This will probably need to be tackled in pieces.

[Gankra]

What needs to be done here? Just cleanup?

[steveklabnik]

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:

1. make sure everything is following doc conventions
2. make sure everything has examples
3. make sure everything is explained well

I don't have any specific goals yet.

[nathankleyn]

As discussed on this Rust subreddit thread, I'll also try to help out by adding some more examples for using the entry API to update/modify a HashMap et al.

[apasel422]

@steveklabnik Some things I've noticed that are relevant to this:

• The use of "create" vs "make" for constructors
• The use of unconventional first lines for iterator-returning methods, e.g. "An iterator visiting all keys in arbitrary order. Iterator element type is &'a K." vs "Gets an iterator over the entries of the map."
• The use of both "element" and "value"

[wthrowe]

The blurb on complex keys in the map insert methods isn't clear that it's talking about complex keys:

If the map did have this key present, that value is returned, and the entry is not updated. See the module-level documentation for more.

It's the key that is not updated. The value is updated. The linked module-level documentation makes this clear.

[nathankleyn]

@steveklabnik 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.

[steveklabnik]

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.

[nathankleyn]

Okay awesome, I might start going through some of them and will add the ones I've checked back here for reference. 👍

[steveklabnik]

That'd be spectacular.

[nathankleyn]

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:

• BTreeMap -> PR Add missing documentation examples for BTreeMap. #32135
• BTreeSet -> PR Add missing documentation examples for BTreeSet. #32136
• BinaryHeap -> PR Add missing documentation examples for BinaryHeap. #32137
• HashMap -> PR Add examples of the Entry API to the HashMap documentation. #31035
• LinkedList
• VecDeque

Collection specific structs:

• btree_map::OccupiedEntry
• btree_map::VacantEntry
• btree_map::Entry
• hash_map::OccupiedEntry
• hash_map::VacantEntry
• hash_map::RandomState
• hash_map::Entry

[steveklabnik]

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 Kleynnotifications@github.com, wrote:

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:

Top level structs:

BTreeMap(http://doc.rust-lang.org/std/collections/struct.BTreeMap.html)
BTreeSet(http://doc.rust-lang.org/std/collections/struct.BTreeSet.html)
BinaryHeap(http://doc.rust-lang.org/std/collections/struct.BinaryHeap.html)
HashMap(http://doc.rust-lang.org/std/collections/struct.HashMap.html)
HashSet(http://doc.rust-lang.org/std/collections/struct.HashSet.html)
LinkedList(http://doc.rust-lang.org/std/collections/struct.LinkedList.html)
VecDeque(http://doc.rust-lang.org/std/collections/struct.VecDeque.html)
Bound(http://doc.rust-lang.org/std/collections/enum.Bound.html)(Unstable; does this need doing?)

Collection specific structs:

btree_map::OccupiedEntry(http://doc.rust-lang.org/std/collections/btree_map/struct.OccupiedEntry.html)
btree_map::VacantEntry(http://doc.rust-lang.org/std/collections/btree_map/struct.VacantEntry.html)
btree_map::Entry(http://doc.rust-lang.org/std/collections/btree_map/enum.Entry.html)
hash_map::OccupiedEntry(http://doc.rust-lang.org/std/collections/hash_map/struct.OccupiedEntry.html)
hash_map::VacantEntry(http://doc.rust-lang.org/std/collections/hash_map/struct.VacantEntry.html)
hash_map::RandomState(http://doc.rust-lang.org/std/collections/hash_map/struct.RandomState.html)
hash_map::Entry(http://doc.rust-lang.org/std/collections/hash_map/enum.Entry.html)
hash_state::HashState(http://doc.rust-lang.org/std/collections/hash_state/trait.HashState.html)(Unstable; does this need doing?)

—
Reply to this email directly orview it on GitHub(#29348 (comment)).