auto merge of #16887 : steveklabnik/rust/guide_iterators, r=alexcrichton

This isn't ready to merge yet.

The 'containers and iterators' guide is basically just a collection of stuff that should be in the module definitions. So I'm moving the guide to just an 'iterators' guide, and moved the info that was there into the right places.

So, is this a good path forward, and is all of the information still correct?

Author: bors

src/doc/guide-container.md

@@ -57,7 +57,6 @@ a guide that can help you out:
 * [Strings](guide-strings.html)
 * [Pointers](guide-pointers.html)
 * [References and Lifetimes](guide-lifetimes.html)
-* [Containers and Iterators](guide-container.html)
 * [Tasks and Communication](guide-tasks.html)
 * [Foreign Function Interface](guide-ffi.html)
 * [Writing Unsafe and Low-Level Code](guide-unsafe.html)

src/doc/index.md

@@ -10,6 +10,11 @@
 
 //! A priority queue implemented with a binary heap.
 //!
+//! Insertions have `O(log n)` time complexity and checking or popping the largest element is
+//! `O(1)`. Converting a vector to a priority queue can be done in-place, and has `O(n)`
+//! complexity. A priority queue can also be converted to a sorted vector in-place, allowing it to
+//! be used for an `O(n log n)` in-place heapsort.
+//!
 //! # Example
 //!
 //! This is a larger example which implements [Dijkstra's algorithm][dijkstra]

src/libcollections/priority_queue.rs

@@ -8,10 +8,10 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! A double-ended queue implemented as a circular buffer.
-//!
-//! `RingBuf` implements the trait `Deque`. It should be imported with
-//! `use collections::Deque`.
+//! This crate implements a double-ended queue with `O(1)` amortized inserts and removals from both
+//! ends of the container. It also has `O(1)` indexing like a vector. The contained elements are
+//! not required to be copyable, and the queue will be sendable if the contained type is sendable.
+//! Its interface `Deque` is defined in `collections`.
 
 use core::prelude::*;
 

src/libcollections/ringbuf.rs

@@ -8,9 +8,13 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! An ordered map and set implemented as self-balancing binary search
-//! trees. The only requirement for the types is that the key implements
-//! `Ord`.
+//! Maps are collections of unique keys with corresponding values, and sets are
+//! just unique keys without a corresponding value. The `Map` and `Set` traits in
+//! `std::container` define the basic interface.
+//!
+//! This crate defines the `TreeMap` and `TreeSet` types. Their keys must implement `Ord`.
+//!
+//! `TreeMap`s are ordered.
 //!
 //! ## Example
 //!

src/libcollections/treemap.rs

@@ -8,8 +8,13 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Ordered containers with unsigned integer keys,
-//! implemented as radix tries (`TrieSet` and `TrieMap` types).
+//! Maps are collections of unique keys with corresponding values, and sets are
+//! just unique keys without a corresponding value. The `Map` and `Set` traits in
+//! `std::container` define the basic interface.
+//!
+//! This crate defines `TrieMap` and `TrieSet`, which require `uint` keys.
+//!
+//! `TrieMap` is ordered.
 
 use core::prelude::*;
 

src/libcollections/trie.rs

@@ -8,7 +8,9 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! An owned, growable vector.
+//! A growable list type, written `Vec<T>` but pronounced 'vector.'
+//!
+//! Vectors have `O(1)` indexing, push (to the end) and pop (from the end).
 
 use core::prelude::*;
 

src/libcollections/vec.rs

@@ -56,12 +56,6 @@ loop {
 
 This `for` loop syntax can be applied to any iterator over any type.
 
-## Iteration protocol and more
-
-More detailed information about iterators can be found in the [container
-guide](http://doc.rust-lang.org/guide-container.html) with
-the rest of the rust manuals.
-
 */
 
 use clone::Clone;