Skip to content

Commit

Permalink
Auto merge of #41286 - lukaramu:std-collections-docs, r=frewsxcv
Browse files Browse the repository at this point in the history 
Various improvements in std::collections docs

The meat of this PR are:
* changes to (almost all?) iterator struct docs in std::collections such that they use the standard iterator boilerplate and state where they are created
* a bunch of added links (at least as much as possible given std::collections mostly being a facade and whatnot 😅)
* an example for `Bound`
* changed phrasing for some summary sentences to be less redundant as well as more consistant with others in the module

There also are various other fixes, e.g. removing parens from method names in the module docs, changing some imperatives to 3rd person, etc.

r? @steveklabnik
  • Loading branch information
@bors
bors committed Apr 15, 2017
2 parents be1a74e + 2a23e6e commit 5f13a3b
Show file tree
Hide file tree
Showing 10 changed files with 415 additions and 146 deletions.
39 changes: 32 additions & 7 deletions src/libcollections/binary_heap.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,12 @@
//!
//! This is a larger example that implements [Dijkstra's algorithm][dijkstra]
//! to solve the [shortest path problem][sssp] on a [directed graph][dir_graph].
//! It shows how to use `BinaryHeap` with custom types.
//! It shows how to use [`BinaryHeap`] with custom types.
//!
//! [dijkstra]: http://en.wikipedia.org/wiki/Dijkstra%27s_algorithm
//! [sssp]: http://en.wikipedia.org/wiki/Shortest_path_problem
//! [dir_graph]: http://en.wikipedia.org/wiki/Directed_graph
//! [`BinaryHeap`]: struct.BinaryHeap.html
//!
//! ```
//! use std::cmp::Ordering;
Expand Down Expand Up @@ -218,10 +219,14 @@ pub struct BinaryHeap<T> {
data: Vec<T>,
}

/// A container object that represents the result of the [`peek_mut`] method
/// on `BinaryHeap`. See its documentation for details.
/// Structure wrapping a mutable reference to the greatest item on a
/// `BinaryHeap`.
///
/// This `struct` is created by the [`peek_mut`] method on [`BinaryHeap`]. See
/// its documentation for more.
///
/// [`peek_mut`]: struct.BinaryHeap.html#method.peek_mut
/// [`BinaryHeap`]: struct.BinaryHeap.html
#[stable(feature = "binary_heap_peek_mut", since = "1.12.0")]
pub struct PeekMut<'a, T: 'a + Ord> {
heap: &'a mut BinaryHeap<T>,
Expand Down Expand Up @@ -434,7 +439,7 @@ impl<T: Ord> BinaryHeap<T> {
/// given `BinaryHeap`. Does nothing if the capacity is already sufficient.
///
/// Note that the allocator may give the collection more space than it requests. Therefore
/// capacity can not be relied upon to be precisely minimal. Prefer `reserve` if future
/// capacity can not be relied upon to be precisely minimal. Prefer [`reserve`] if future
/// insertions are expected.
///
/// # Panics
Expand All @@ -452,6 +457,8 @@ impl<T: Ord> BinaryHeap<T> {
/// assert!(heap.capacity() >= 100);
/// heap.push(4);
/// ```
///
/// [`reserve`]: #method.reserve
#[stable(feature = "rust1", since = "1.0.0")]
pub fn reserve_exact(&mut self, additional: usize) {
self.data.reserve_exact(additional);
Expand Down Expand Up @@ -971,7 +978,13 @@ impl<'a, T> Drop for Hole<'a, T> {
}
}

/// `BinaryHeap` iterator.
/// An iterator over the elements of a `BinaryHeap`.
///
/// This `struct` is created by the [`iter`] method on [`BinaryHeap`]. See its
/// documentation for more.
///
/// [`iter`]: struct.BinaryHeap.html#method.iter
/// [`BinaryHeap`]: struct.BinaryHeap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Iter<'a, T: 'a> {
iter: slice::Iter<'a, T>,
Expand Down Expand Up @@ -1027,7 +1040,13 @@ impl<'a, T> ExactSizeIterator for Iter<'a, T> {
#[unstable(feature = "fused", issue = "35602")]
impl<'a, T> FusedIterator for Iter<'a, T> {}

/// An iterator that moves out of a `BinaryHeap`.
/// An owning iterator over the elements of a `BinaryHeap`.
///
/// This `struct` is created by the [`into_iter`] method on [`BinaryHeap`]
/// (provided by the `IntoIterator` trait). See its documentation for more.
///
/// [`into_iter`]: struct.BinaryHeap.html#method.into_iter
/// [`BinaryHeap`]: struct.BinaryHeap.html
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Clone)]
pub struct IntoIter<T> {
Expand Down Expand Up @@ -1076,7 +1095,13 @@ impl<T> ExactSizeIterator for IntoIter<T> {
#[unstable(feature = "fused", issue = "35602")]
impl<T> FusedIterator for IntoIter<T> {}

/// An iterator that drains a `BinaryHeap`.
/// A draining iterator over the elements of a `BinaryHeap`.
///
/// This `struct` is created by the [`drain`] method on [`BinaryHeap`]. See its
/// documentation for more.
///
/// [`drain`]: struct.BinaryHeap.html#method.drain
/// [`BinaryHeap`]: struct.BinaryHeap.html
#[stable(feature = "drain", since = "1.6.0")]
#[derive(Debug)]
pub struct Drain<'a, T: 'a> {
Expand Down
77 changes: 64 additions & 13 deletions src/libcollections/btree/map.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,13 @@ impl<K, Q: ?Sized> super::Recover<Q> for BTreeMap<K, ()>
}
}

/// An iterator over a `BTreeMap`'s entries.
/// An iterator over the entries of a `BTreeMap`.
///
/// This `struct` is created by the [`iter`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`iter`]: struct.BTreeMap.html#method.iter
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Iter<'a, K: 'a, V: 'a> {
range: Range<'a, K, V>,
Expand All @@ -276,15 +282,27 @@ impl<'a, K: 'a + fmt::Debug, V: 'a + fmt::Debug> fmt::Debug for Iter<'a, K, V> {
}
}

/// A mutable iterator over a `BTreeMap`'s entries.
/// A mutable iterator over the entries of a `BTreeMap`.
///
/// This `struct` is created by the [`iter_mut`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`iter_mut`]: struct.BTreeMap.html#method.iter_mut
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct IterMut<'a, K: 'a, V: 'a> {
range: RangeMut<'a, K, V>,
length: usize,
}

/// An owning iterator over a `BTreeMap`'s entries.
/// An owning iterator over the entries of a `BTreeMap`.
///
/// This `struct` is created by the [`into_iter`] method on [`BTreeMap`]
/// (provided by the `IntoIterator` trait). See its documentation for more.
///
/// [`into_iter`]: struct.BTreeMap.html#method.into_iter
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct IntoIter<K, V> {
front: Handle<NodeRef<marker::Owned, K, V, marker::Leaf>, marker::Edge>,
Expand All @@ -303,7 +321,13 @@ impl<K: fmt::Debug, V: fmt::Debug> fmt::Debug for IntoIter<K, V> {
}
}

/// An iterator over a `BTreeMap`'s keys.
/// An iterator over the keys of a `BTreeMap`.
///
/// This `struct` is created by the [`keys`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`keys`]: struct.BTreeMap.html#method.keys
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Keys<'a, K: 'a, V: 'a> {
inner: Iter<'a, K, V>,
Expand All @@ -316,7 +340,13 @@ impl<'a, K: 'a + fmt::Debug, V: 'a + fmt::Debug> fmt::Debug for Keys<'a, K, V> {
}
}

/// An iterator over a `BTreeMap`'s values.
/// An iterator over the values of a `BTreeMap`.
///
/// This `struct` is created by the [`values`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`values`]: struct.BTreeMap.html#method.values
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Values<'a, K: 'a, V: 'a> {
inner: Iter<'a, K, V>,
Expand All @@ -329,14 +359,26 @@ impl<'a, K: 'a + fmt::Debug, V: 'a + fmt::Debug> fmt::Debug for Values<'a, K, V>
}
}

/// A mutable iterator over a `BTreeMap`'s values.
/// A mutable iterator over the values of a `BTreeMap`.
///
/// This `struct` is created by the [`values_mut`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`values_mut`]: struct.BTreeMap.html#method.values_mut
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "map_values_mut", since = "1.10.0")]
#[derive(Debug)]
pub struct ValuesMut<'a, K: 'a, V: 'a> {
inner: IterMut<'a, K, V>,
}

/// An iterator over a sub-range of `BTreeMap`'s entries.
/// An iterator over a sub-range of entries in a `BTreeMap`.
///
/// This `struct` is created by the [`range`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`range`]: struct.BTreeMap.html#method.range
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "btree_range", since = "1.17.0")]
pub struct Range<'a, K: 'a, V: 'a> {
front: Handle<NodeRef<marker::Immut<'a>, K, V, marker::Leaf>, marker::Edge>,
Expand All @@ -350,7 +392,13 @@ impl<'a, K: 'a + fmt::Debug, V: 'a + fmt::Debug> fmt::Debug for Range<'a, K, V>
}
}

/// A mutable iterator over a sub-range of `BTreeMap`'s entries.
/// A mutable iterator over a sub-range of entries in a `BTreeMap`.
///
/// This `struct` is created by the [`range_mut`] method on [`BTreeMap`]. See its
/// documentation for more.
///
/// [`range_mut`]: struct.BTreeMap.html#method.range_mut
/// [`BTreeMap`]: struct.BTreeMap.html
#[stable(feature = "btree_range", since = "1.17.0")]
pub struct RangeMut<'a, K: 'a, V: 'a> {
front: Handle<NodeRef<marker::Mut<'a>, K, V, marker::Leaf>, marker::Edge>,
Expand All @@ -372,18 +420,19 @@ impl<'a, K: 'a + fmt::Debug, V: 'a + fmt::Debug> fmt::Debug for RangeMut<'a, K,
}

/// A view into a single entry in a map, which may either be vacant or occupied.
/// This enum is constructed from the [`entry`] method on [`BTreeMap`].
///
/// This `enum` is constructed from the [`entry`] method on [`BTreeMap`].
///
/// [`BTreeMap`]: struct.BTreeMap.html
/// [`entry`]: struct.BTreeMap.html#method.entry
#[stable(feature = "rust1", since = "1.0.0")]
pub enum Entry<'a, K: 'a, V: 'a> {
/// A vacant `Entry`
/// A vacant entry.
#[stable(feature = "rust1", since = "1.0.0")]
Vacant(#[stable(feature = "rust1", since = "1.0.0")]
VacantEntry<'a, K, V>),

/// An occupied `Entry`
/// An occupied entry.
#[stable(feature = "rust1", since = "1.0.0")]
Occupied(#[stable(feature = "rust1", since = "1.0.0")]
OccupiedEntry<'a, K, V>),
Expand All @@ -403,7 +452,8 @@ impl<'a, K: 'a + Debug + Ord, V: 'a + Debug> Debug for Entry<'a, K, V> {
}
}

/// A vacant `Entry`. It is part of the [`Entry`] enum.
/// A view into a vacant entry in a `BTreeMap`.
/// It is part of the [`Entry`] enum.
///
/// [`Entry`]: enum.Entry.html
#[stable(feature = "rust1", since = "1.0.0")]
Expand All @@ -425,7 +475,8 @@ impl<'a, K: 'a + Debug + Ord, V: 'a> Debug for VacantEntry<'a, K, V> {
}
}

/// An occupied `Entry`. It is part of the [`Entry`] enum.
/// A view into an occupied entry in a `BTreeMap`.
/// It is part of the [`Entry`] enum.
///
/// [`Entry`]: enum.Entry.html
#[stable(feature = "rust1", since = "1.0.0")]
Expand Down
40 changes: 23 additions & 17 deletions src/libcollections/btree/set.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,10 @@ pub struct BTreeSet<T> {
map: BTreeMap<T, ()>,
}

/// An iterator over a `BTreeSet`'s items.
/// An iterator over the items of a `BTreeSet`.
///
/// This structure is created by the [`iter`] method on [`BTreeSet`].
/// This `struct` is created by the [`iter`] method on [`BTreeSet`].
/// See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`iter`]: struct.BTreeSet.html#method.iter
Expand All @@ -94,21 +95,23 @@ impl<'a, T: 'a + fmt::Debug> fmt::Debug for Iter<'a, T> {
}
}

/// An owning iterator over a `BTreeSet`'s items.
/// An owning iterator over the items of a `BTreeSet`.
///
/// This structure is created by the `into_iter` method on [`BTreeSet`]
/// [`BTreeSet`] (provided by the `IntoIterator` trait).
/// This `struct` is created by the [`into_iter`] method on [`BTreeSet`]
/// (provided by the `IntoIterator` trait). See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`into_iter`]: struct.BTreeSet.html#method.into_iter
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct IntoIter<T> {
iter: ::btree_map::IntoIter<T, ()>,
}

/// An iterator over a sub-range of `BTreeSet`'s items.
/// An iterator over a sub-range of items in a `BTreeSet`.
///
/// This structure is created by the [`range`] method on [`BTreeSet`].
/// This `struct` is created by the [`range`] method on [`BTreeSet`].
/// See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`range`]: struct.BTreeSet.html#method.range
Expand All @@ -118,9 +121,10 @@ pub struct Range<'a, T: 'a> {
iter: ::btree_map::Range<'a, T, ()>,
}

/// A lazy iterator producing elements in the set difference (in-order).
/// A lazy iterator producing elements in the difference of `BTreeSet`s.
///
/// This structure is created by the [`difference`] method on [`BTreeSet`].
/// This `struct` is created by the [`difference`] method on [`BTreeSet`].
/// See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`difference`]: struct.BTreeSet.html#method.difference
Expand All @@ -139,10 +143,10 @@ impl<'a, T: 'a + fmt::Debug> fmt::Debug for Difference<'a, T> {
}
}

/// A lazy iterator producing elements in the set symmetric difference (in-order).
/// A lazy iterator producing elements in the symmetric difference of `BTreeSet`s.
///
/// This structure is created by the [`symmetric_difference`] method on
/// [`BTreeSet`].
/// This `struct` is created by the [`symmetric_difference`] method on
/// [`BTreeSet`]. See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`symmetric_difference`]: struct.BTreeSet.html#method.symmetric_difference
Expand All @@ -161,9 +165,10 @@ impl<'a, T: 'a + fmt::Debug> fmt::Debug for SymmetricDifference<'a, T> {
}
}

/// A lazy iterator producing elements in the set intersection (in-order).
/// A lazy iterator producing elements in the intersection of `BTreeSet`s.
///
/// This structure is created by the [`intersection`] method on [`BTreeSet`].
/// This `struct` is created by the [`intersection`] method on [`BTreeSet`].
/// See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`intersection`]: struct.BTreeSet.html#method.intersection
Expand All @@ -182,9 +187,10 @@ impl<'a, T: 'a + fmt::Debug> fmt::Debug for Intersection<'a, T> {
}
}

/// A lazy iterator producing elements in the set union (in-order).
/// A lazy iterator producing elements in the union of `BTreeSet`s.
///
/// This structure is created by the [`union`] method on [`BTreeSet`].
/// This `struct` is created by the [`union`] method on [`BTreeSet`].
/// See its documentation for more.
///
/// [`BTreeSet`]: struct.BTreeSet.html
/// [`union`]: struct.BTreeSet.html#method.union
Expand Down Expand Up @@ -728,7 +734,7 @@ impl<T> IntoIterator for BTreeSet<T> {
type Item = T;
type IntoIter = IntoIter<T>;

/// Gets an iterator for moving out the BtreeSet's contents.
/// Gets an iterator for moving out the `BTreeSet`'s contents.
///
/// # Examples
///
Expand Down
Loading

0 comments on commit 5f13a3b

Please sign in to comment.