diff --git a/src/libcollections/binary_heap.rs b/src/libcollections/binary_heap.rs index efa96ca468e01..149c285a72a98 100644 --- a/src/libcollections/binary_heap.rs +++ b/src/libcollections/binary_heap.rs @@ -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; @@ -218,10 +219,14 @@ pub struct BinaryHeap { data: Vec, } -/// 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, @@ -434,7 +439,7 @@ impl BinaryHeap { /// 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 @@ -452,6 +457,8 @@ impl BinaryHeap { /// 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); @@ -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>, @@ -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 { @@ -1076,7 +1095,13 @@ impl ExactSizeIterator for IntoIter { #[unstable(feature = "fused", issue = "35602")] impl FusedIterator for IntoIter {} -/// 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> { diff --git a/src/libcollections/btree/map.rs b/src/libcollections/btree/map.rs index b30700c3f694e..b986c0275502c 100644 --- a/src/libcollections/btree/map.rs +++ b/src/libcollections/btree/map.rs @@ -262,7 +262,13 @@ impl super::Recover for BTreeMap } } -/// 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>, @@ -276,7 +282,13 @@ 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> { @@ -284,7 +296,13 @@ pub struct IterMut<'a, K: 'a, V: 'a> { 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 { front: Handle, marker::Edge>, @@ -303,7 +321,13 @@ impl fmt::Debug for IntoIter { } } -/// 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>, @@ -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>, @@ -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, K, V, marker::Leaf>, marker::Edge>, @@ -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, K, V, marker::Leaf>, marker::Edge>, @@ -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>), @@ -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")] @@ -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")] diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs index 9dbb61379379e..ffca6964c5fdf 100644 --- a/src/libcollections/btree/set.rs +++ b/src/libcollections/btree/set.rs @@ -74,9 +74,10 @@ pub struct BTreeSet { map: BTreeMap, } -/// 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 @@ -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 { iter: ::btree_map::IntoIter, } -/// 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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -728,7 +734,7 @@ impl IntoIterator for BTreeSet { type Item = T; type IntoIter = IntoIter; - /// Gets an iterator for moving out the BtreeSet's contents. + /// Gets an iterator for moving out the `BTreeSet`'s contents. /// /// # Examples /// diff --git a/src/libcollections/lib.rs b/src/libcollections/lib.rs index 99afd08e81183..a207087915a3d 100644 --- a/src/libcollections/lib.rs +++ b/src/libcollections/lib.rs @@ -135,6 +135,42 @@ mod std { } /// An endpoint of a range of keys. +/// +/// # Examples +/// +/// `Bound`s are range endpoints: +/// +/// ``` +/// #![feature(collections_range)] +/// +/// use std::collections::range::RangeArgument; +/// use std::collections::Bound::*; +/// +/// assert_eq!((..100).start(), Unbounded); +/// assert_eq!((1..12).start(), Included(&1)); +/// assert_eq!((1..12).end(), Excluded(&12)); +/// ``` +/// +/// Using a tuple of `Bound`s as an argument to [`BTreeMap::range`]. +/// Note that in most cases, it's better to use range syntax (`1..5`) instead. +/// +/// ``` +/// use std::collections::BTreeMap; +/// use std::collections::Bound::{Excluded, Included, Unbounded}; +/// +/// let mut map = BTreeMap::new(); +/// map.insert(3, "a"); +/// map.insert(5, "b"); +/// map.insert(8, "c"); +/// +/// for (key, value) in map.range((Excluded(3), Included(8))) { +/// println!("{}: {}", key, value); +/// } +/// +/// assert_eq!(Some((&3, &"a")), map.range((Unbounded, Included(5))).next()); +/// ``` +/// +/// [`BTreeMap::range`]: btree_map/struct.BTreeMap.html#method.range #[stable(feature = "collections_bound", since = "1.17.0")] #[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)] pub enum Bound { diff --git a/src/libcollections/linked_list.rs b/src/libcollections/linked_list.rs index 1b3eeb837d909..bfb03a5b23f1d 100644 --- a/src/libcollections/linked_list.rs +++ b/src/libcollections/linked_list.rs @@ -56,7 +56,13 @@ struct Node { element: T, } -/// An iterator over references to the elements of a `LinkedList`. +/// An iterator over the elements of a `LinkedList`. +/// +/// This `struct` is created by the [`iter`] method on [`LinkedList`]. See its +/// documentation for more. +/// +/// [`iter`]: struct.LinkedList.html#method.iter +/// [`LinkedList`]: struct.LinkedList.html #[stable(feature = "rust1", since = "1.0.0")] pub struct Iter<'a, T: 'a> { head: Option>>, @@ -82,7 +88,13 @@ impl<'a, T> Clone for Iter<'a, T> { } } -/// An iterator over mutable references to the elements of a `LinkedList`. +/// A mutable iterator over the elements of a `LinkedList`. +/// +/// This `struct` is created by the [`iter_mut`] method on [`LinkedList`]. See its +/// documentation for more. +/// +/// [`iter_mut`]: struct.LinkedList.html#method.iter_mut +/// [`LinkedList`]: struct.LinkedList.html #[stable(feature = "rust1", since = "1.0.0")] pub struct IterMut<'a, T: 'a> { list: &'a mut LinkedList, @@ -100,7 +112,13 @@ impl<'a, T: 'a + fmt::Debug> fmt::Debug for IterMut<'a, T> { } } -/// An iterator over the elements of a `LinkedList`. +/// An owning iterator over the elements of a `LinkedList`. +/// +/// This `struct` is created by the [`into_iter`] method on [`LinkedList`] +/// (provided by the `IntoIterator` trait). See its documentation for more. +/// +/// [`into_iter`]: struct.LinkedList.html#method.into_iter +/// [`LinkedList`]: struct.LinkedList.html #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] pub struct IntoIter { @@ -618,12 +636,12 @@ impl LinkedList { /// Splits the list into two at the given index. Returns everything after the given index, /// including the index. /// + /// This operation should compute in O(n) time. + /// /// # Panics /// /// Panics if `at > len`. /// - /// This operation should compute in O(n) time. - /// /// # Examples /// /// ``` diff --git a/src/libcollections/vec_deque.rs b/src/libcollections/vec_deque.rs index f1ea0010e98c2..2ce3b92843bd7 100644 --- a/src/libcollections/vec_deque.rs +++ b/src/libcollections/vec_deque.rs @@ -8,8 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! `VecDeque` is a double-ended queue, which is implemented with the help of a -//! growing ring buffer. +//! A double-ended queue implemented with a growable ring buffer. //! //! This queue has `O(1)` amortized inserts and removals from both ends of the //! container. It also has `O(1)` indexing like a vector. The contained elements @@ -43,13 +42,17 @@ const MAXIMUM_ZST_CAPACITY: usize = 1 << (32 - 1); // Largest possible power of #[cfg(target_pointer_width = "64")] const MAXIMUM_ZST_CAPACITY: usize = 1 << (64 - 1); // Largest possible power of two -/// `VecDeque` is a growable ring buffer, which can be used as a double-ended -/// queue efficiently. +/// A double-ended queue implemented with a growable ring buffer. /// -/// The "default" usage of this type as a queue is to use `push_back` to add to -/// the queue, and `pop_front` to remove from the queue. `extend` and `append` +/// The "default" usage of this type as a queue is to use [`push_back`] to add to +/// the queue, and [`pop_front`] to remove from the queue. [`extend`] and [`append`] /// push onto the back in this manner, and iterating over `VecDeque` goes front /// to back. +/// +/// [`push_back`]: #method.push_back +/// [`pop_front`]: #method.pop_front +/// [`extend`]: #method.extend +/// [`append`]: #method.append #[stable(feature = "rust1", since = "1.0.0")] pub struct VecDeque { // tail and head are pointers into the buffer. Tail always points @@ -506,7 +509,7 @@ impl VecDeque { /// given `VecDeque`. 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 @@ -522,6 +525,8 @@ impl VecDeque { /// buf.reserve_exact(10); /// assert!(buf.capacity() >= 11); /// ``` + /// + /// [`reserve`]: #method.reserve #[stable(feature = "rust1", since = "1.0.0")] pub fn reserve_exact(&mut self, additional: usize) { self.reserve(additional); @@ -1890,7 +1895,13 @@ fn count(tail: usize, head: usize, size: usize) -> usize { (head.wrapping_sub(tail)) & (size - 1) } -/// `VecDeque` iterator. +/// An iterator over the elements of a `VecDeque`. +/// +/// This `struct` is created by the [`iter`] method on [`VecDeque`]. See its +/// documentation for more. +/// +/// [`iter`]: struct.VecDeque.html#method.iter +/// [`VecDeque`]: struct.VecDeque.html #[stable(feature = "rust1", since = "1.0.0")] pub struct Iter<'a, T: 'a> { ring: &'a [T], @@ -1971,7 +1982,13 @@ impl<'a, T> ExactSizeIterator for Iter<'a, T> { impl<'a, T> FusedIterator for Iter<'a, T> {} -/// `VecDeque` mutable iterator. +/// A mutable iterator over the elements of a `VecDeque`. +/// +/// This `struct` is created by the [`iter_mut`] method on [`VecDeque`]. See its +/// documentation for more. +/// +/// [`iter_mut`]: struct.VecDeque.html#method.iter_mut +/// [`VecDeque`]: struct.VecDeque.html #[stable(feature = "rust1", since = "1.0.0")] pub struct IterMut<'a, T: 'a> { ring: &'a mut [T], @@ -2047,7 +2064,13 @@ impl<'a, T> ExactSizeIterator for IterMut<'a, T> { #[unstable(feature = "fused", issue = "35602")] impl<'a, T> FusedIterator for IterMut<'a, T> {} -/// A by-value `VecDeque` iterator +/// An owning iterator over the elements of a `VecDeque`. +/// +/// This `struct` is created by the [`into_iter`] method on [`VecDeque`] +/// (provided by the `IntoIterator` trait). See its documentation for more. +/// +/// [`into_iter`]: struct.VecDeque.html#method.into_iter +/// [`VecDeque`]: struct.VecDeque.html #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] pub struct IntoIter { @@ -2097,7 +2120,13 @@ impl ExactSizeIterator for IntoIter { #[unstable(feature = "fused", issue = "35602")] impl FusedIterator for IntoIter {} -/// A draining `VecDeque` iterator +/// A draining iterator over the elements of a `VecDeque`. +/// +/// This `struct` is created by the [`drain`] method on [`VecDeque`]. See its +/// documentation for more. +/// +/// [`drain`]: struct.VecDeque.html#method.drain +/// [`VecDeque`]: struct.VecDeque.html #[stable(feature = "drain", since = "1.6.0")] pub struct Drain<'a, T: 'a> { after_tail: usize, diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs index a06299eaefe0a..eacb59d375a50 100644 --- a/src/libstd/collections/hash/map.rs +++ b/src/libstd/collections/hash/map.rs @@ -215,8 +215,7 @@ const DISPLACEMENT_THRESHOLD: usize = 128; // 1. Alfredo Viola (2005). Distributional analysis of Robin Hood linear probing // hashing with buckets. -/// A hash map implementation which uses linear probing with Robin Hood bucket -/// stealing. +/// A hash map implemented with linear probing and Robin Hood bucket stealing. /// /// By default, `HashMap` uses a hashing algorithm selected to provide /// resistance against HashDoS attacks. The algorithm is randomly seeded, and a @@ -235,9 +234,8 @@ const DISPLACEMENT_THRESHOLD: usize = 128; /// attacks such as HashDoS. /// /// The hashing algorithm can be replaced on a per-`HashMap` basis using the -/// [`HashMap::default`], [`HashMap::with_hasher`], and -/// [`HashMap::with_capacity_and_hasher`] methods. Many alternative algorithms -/// are available on crates.io, such as the [`fnv`] crate. +/// [`default`], [`with_hasher`], and [`with_capacity_and_hasher`] methods. Many +/// alternative algorithms are available on crates.io, such as the [`fnv`] crate. /// /// It is required that the keys implement the [`Eq`] and [`Hash`] traits, although /// this can frequently be achieved by using `#[derive(PartialEq, Eq, Hash)]`. @@ -339,9 +337,9 @@ const DISPLACEMENT_THRESHOLD: usize = 128; /// [`PartialEq`]: ../../std/cmp/trait.PartialEq.html /// [`RefCell`]: ../../std/cell/struct.RefCell.html /// [`Cell`]: ../../std/cell/struct.Cell.html -/// [`HashMap::default`]: #method.default -/// [`HashMap::with_hasher`]: #method.with_hasher -/// [`HashMap::with_capacity_and_hasher`]: #method.with_capacity_and_hasher +/// [`default`]: #method.default +/// [`with_hasher`]: #method.with_hasher +/// [`with_capacity_and_hasher`]: #method.with_capacity_and_hasher /// [`fnv`]: https://crates.io/crates/fnv /// /// ``` @@ -373,7 +371,7 @@ const DISPLACEMENT_THRESHOLD: usize = 128; /// } /// ``` /// -/// A HashMap with fixed list of elements can be initialized from an array: +/// A `HashMap` with fixed list of elements can be initialized from an array: /// /// ``` /// use std::collections::HashMap; @@ -654,12 +652,13 @@ impl HashMap } } - /// Creates an empty `HashMap` with the specified capacity, using `hasher` + /// Creates an empty `HashMap` with the specified capacity, using `hash_builder` /// to hash the keys. /// /// The hash map will be able to hold at least `capacity` elements without /// reallocating. If `capacity` is 0, the hash map will not allocate. - /// Warning: `hasher` is normally randomly generated, and + /// + /// Warning: `hash_builder` is normally randomly generated, and /// is designed to allow HashMaps to be resistant to attacks that /// cause many collisions and very poor performance. Setting it /// manually using this function can expose a DoS attack vector. @@ -686,7 +685,9 @@ impl HashMap } } - /// Returns a reference to the map's hasher. + /// Returns a reference to the map's [`BuildHasher`]. + /// + /// [`BuildHasher`]: ../../std/hash/trait.BuildHasher.html #[stable(feature = "hashmap_public_hasher", since = "1.9.0")] pub fn hasher(&self) -> &S { &self.hash_builder @@ -849,7 +850,7 @@ impl HashMap } /// An iterator visiting all keys in arbitrary order. - /// Iterator element type is `&'a K`. + /// The iterator element type is `&'a K`. /// /// # Examples /// @@ -871,7 +872,7 @@ impl HashMap } /// An iterator visiting all values in arbitrary order. - /// Iterator element type is `&'a V`. + /// The iterator element type is `&'a V`. /// /// # Examples /// @@ -893,7 +894,7 @@ impl HashMap } /// An iterator visiting all values mutably in arbitrary order. - /// Iterator element type is `&'a mut V`. + /// The iterator element type is `&'a mut V`. /// /// # Examples /// @@ -920,7 +921,7 @@ impl HashMap } /// An iterator visiting all key-value pairs in arbitrary order. - /// Iterator element type is `(&'a K, &'a V)`. + /// The iterator element type is `(&'a K, &'a V)`. /// /// # Examples /// @@ -943,7 +944,7 @@ impl HashMap /// An iterator visiting all key-value pairs in arbitrary order, /// with mutable references to the values. - /// Iterator element type is `(&'a K, &'a mut V)`. + /// The iterator element type is `(&'a K, &'a mut V)`. /// /// # Examples /// @@ -1333,7 +1334,13 @@ impl<'a, K, Q: ?Sized, V, S> Index<&'a Q> for HashMap } } -/// HashMap iterator. +/// An iterator over the entries of a `HashMap`. +/// +/// This `struct` is created by the [`iter`] method on [`HashMap`]. See its +/// documentation for more. +/// +/// [`iter`]: struct.HashMap.html#method.iter +/// [`HashMap`]: struct.HashMap.html #[stable(feature = "rust1", since = "1.0.0")] pub struct Iter<'a, K: 'a, V: 'a> { inner: table::Iter<'a, K, V>, @@ -1356,19 +1363,37 @@ impl<'a, K: Debug, V: Debug> fmt::Debug for Iter<'a, K, V> { } } -/// HashMap mutable values iterator. +/// A mutable iterator over the entries of a `HashMap`. +/// +/// This `struct` is created by the [`iter_mut`] method on [`HashMap`]. See its +/// documentation for more. +/// +/// [`iter_mut`]: struct.HashMap.html#method.iter_mut +/// [`HashMap`]: struct.HashMap.html #[stable(feature = "rust1", since = "1.0.0")] pub struct IterMut<'a, K: 'a, V: 'a> { inner: table::IterMut<'a, K, V>, } -/// HashMap move iterator. +/// An owning iterator over the entries of a `HashMap`. +/// +/// This `struct` is created by the [`into_iter`] method on [`HashMap`] +/// (provided by the `IntoIterator` trait). See its documentation for more. +/// +/// [`into_iter`]: struct.HashMap.html#method.into_iter +/// [`HashMap`]: struct.HashMap.html #[stable(feature = "rust1", since = "1.0.0")] pub struct IntoIter { pub(super) inner: table::IntoIter, } -/// HashMap keys iterator. +/// An iterator over the keys of a `HashMap`. +/// +/// This `struct` is created by the [`keys`] method on [`HashMap`]. See its +/// documentation for more. +/// +/// [`keys`]: struct.HashMap.html#method.keys +/// [`HashMap`]: struct.HashMap.html #[stable(feature = "rust1", since = "1.0.0")] pub struct Keys<'a, K: 'a, V: 'a> { inner: Iter<'a, K, V>, @@ -1391,7 +1416,13 @@ impl<'a, K: Debug, V: Debug> fmt::Debug for Keys<'a, K, V> { } } -/// HashMap values iterator. +/// An iterator over the values of a `HashMap`. +/// +/// This `struct` is created by the [`values`] method on [`HashMap`]. See its +/// documentation for more. +/// +/// [`values`]: struct.HashMap.html#method.values +/// [`HashMap`]: struct.HashMap.html #[stable(feature = "rust1", since = "1.0.0")] pub struct Values<'a, K: 'a, V: 'a> { inner: Iter<'a, K, V>, @@ -1414,13 +1445,25 @@ impl<'a, K: Debug, V: Debug> fmt::Debug for Values<'a, K, V> { } } -/// HashMap drain iterator. +/// A draining iterator over the entries of a `HashMap`. +/// +/// This `struct` is created by the [`drain`] method on [`HashMap`]. See its +/// documentation for more. +/// +/// [`drain`]: struct.HashMap.html#method.drain +/// [`HashMap`]: struct.HashMap.html #[stable(feature = "drain", since = "1.6.0")] pub struct Drain<'a, K: 'a, V: 'a> { pub(super) inner: table::Drain<'a, K, V>, } -/// Mutable HashMap values iterator. +/// A mutable iterator over the values of a `HashMap`. +/// +/// This `struct` is created by the [`values_mut`] method on [`HashMap`]. See its +/// documentation for more. +/// +/// [`values_mut`]: struct.HashMap.html#method.values_mut +/// [`HashMap`]: struct.HashMap.html #[stable(feature = "map_values_mut", since = "1.10.0")] pub struct ValuesMut<'a, K: 'a, V: 'a> { inner: IterMut<'a, K, V>, @@ -1467,19 +1510,20 @@ impl<'a, K, V> InternalEntry> { } } -/// A view into a single location in a map, which may be vacant or occupied. -/// This enum is constructed from the [`entry`] method on [`HashMap`]. +/// 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 [`HashMap`]. /// /// [`HashMap`]: struct.HashMap.html /// [`entry`]: struct.HashMap.html#method.entry #[stable(feature = "rust1", since = "1.0.0")] pub enum Entry<'a, K: 'a, V: 'a> { - /// 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>), - /// 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>), @@ -1503,7 +1547,7 @@ impl<'a, K: 'a + Debug, V: 'a + Debug> Debug for Entry<'a, K, V> { } } -/// A view into a single occupied location in a HashMap. +/// A view into an occupied entry in a `HashMap`. /// It is part of the [`Entry`] enum. /// /// [`Entry`]: enum.Entry.html @@ -1523,7 +1567,7 @@ impl<'a, K: 'a + Debug, V: 'a + Debug> Debug for OccupiedEntry<'a, K, V> { } } -/// A view into a single empty location in a HashMap. +/// A view into a vacant entry in a `HashMap`. /// It is part of the [`Entry`] enum. /// /// [`Entry`]: enum.Entry.html @@ -2366,10 +2410,9 @@ impl DefaultHasher { #[stable(feature = "hashmap_default_hasher", since = "1.13.0")] impl Default for DefaultHasher { - /// Creates a new `DefaultHasher` using [`DefaultHasher::new`]. See - /// [`DefaultHasher::new`] documentation for more information. + /// Creates a new `DefaultHasher` using [`new`]. See its documentation for more. /// - /// [`DefaultHasher::new`]: #method.new + /// [`new`]: #method.new fn default() -> DefaultHasher { DefaultHasher::new() } diff --git a/src/libstd/collections/hash/set.rs b/src/libstd/collections/hash/set.rs index ac0d15472c1bf..e3fad28502573 100644 --- a/src/libstd/collections/hash/set.rs +++ b/src/libstd/collections/hash/set.rs @@ -24,11 +24,10 @@ use super::map::{self, HashMap, Keys, RandomState}; // for `bucket.val` in the case of HashSet. I suppose we would need HKT // to get rid of it properly. -/// An implementation of a hash set using the underlying representation of a -/// HashMap where the value is (). +/// A hash set implemented as a `HashMap` where the value is `()`. /// -/// As with the `HashMap` type, a `HashSet` requires that the elements -/// implement the `Eq` and `Hash` traits. This can frequently be achieved by +/// As with the [`HashMap`] type, a `HashSet` requires that the elements +/// implement the [`Eq`] and [`Hash`] traits. This can frequently be achieved by /// using `#[derive(PartialEq, Eq, Hash)]`. If you implement these yourself, /// it is important that the following property holds: /// @@ -40,9 +39,9 @@ use super::map::{self, HashMap, Keys, RandomState}; /// /// /// It is a logic error for an item to be modified in such a way that the -/// item's hash, as determined by the `Hash` trait, or its equality, as -/// determined by the `Eq` trait, changes while it is in the set. This is -/// normally only possible through `Cell`, `RefCell`, global state, I/O, or +/// item's hash, as determined by the [`Hash`] trait, or its equality, as +/// determined by the [`Eq`] trait, changes while it is in the set. This is +/// normally only possible through [`Cell`], [`RefCell`], global state, I/O, or /// unsafe code. /// /// # Examples @@ -75,8 +74,8 @@ use super::map::{self, HashMap, Keys, RandomState}; /// ``` /// /// The easiest way to use `HashSet` with a custom type is to derive -/// `Eq` and `Hash`. We must also derive `PartialEq`, this will in the -/// future be implied by `Eq`. +/// [`Eq`] and [`Hash`]. We must also derive [`PartialEq`], this will in the +/// future be implied by [`Eq`]. /// /// ``` /// use std::collections::HashSet; @@ -99,7 +98,7 @@ use super::map::{self, HashMap, Keys, RandomState}; /// } /// ``` /// -/// HashSet with fixed list of elements can be initialized from an array: +/// A `HashSet` with fixed list of elements can be initialized from an array: /// /// ``` /// use std::collections::HashSet; @@ -110,6 +109,13 @@ use super::map::{self, HashMap, Keys, RandomState}; /// // use the values stored in the set /// } /// ``` +/// +/// [`Cell`]: ../../std/cell/struct.Cell.html +/// [`Eq`]: ../../std/cmp/trait.Eq.html +/// [`Hash`]: ../../std/hash/trait.Hash.html +/// [`HashMap`]: struct.HashMap.html +/// [`PartialEq`]: ../../std/cmp/trait.PartialEq.html +/// [`RefCell`]: ../../std/cell/struct.RefCell.html #[derive(Clone)] @@ -181,7 +187,7 @@ impl HashSet HashSet { map: HashMap::with_hasher(hasher) } } - /// Creates an empty HashSet with with the specified capacity, using + /// Creates an empty `HashSet` with with the specified capacity, using /// `hasher` to hash the keys. /// /// The hash set will be able to hold at least `capacity` elements without @@ -208,7 +214,9 @@ impl HashSet HashSet { map: HashMap::with_capacity_and_hasher(capacity, hasher) } } - /// Returns a reference to the set's hasher. + /// Returns a reference to the set's [`BuildHasher`]. + /// + /// [`BuildHasher`]: ../../std/hash/trait.BuildHasher.html #[stable(feature = "hashmap_public_hasher", since = "1.9.0")] pub fn hasher(&self) -> &S { self.map.hasher() @@ -271,7 +279,7 @@ impl HashSet } /// An iterator visiting all elements in arbitrary order. - /// Iterator element type is &'a T. + /// The iterator element type is `&'a T`. /// /// # Examples /// @@ -291,7 +299,7 @@ impl HashSet Iter { iter: self.map.keys() } } - /// Visit the values representing the difference, + /// Visits the values representing the difference, /// i.e. the values that are in `self` but not in `other`. /// /// # Examples @@ -322,7 +330,7 @@ impl HashSet } } - /// Visit the values representing the symmetric difference, + /// Visits the values representing the symmetric difference, /// i.e. the values that are in `self` or in `other` but not in both. /// /// # Examples @@ -350,7 +358,7 @@ impl HashSet SymmetricDifference { iter: self.difference(other).chain(other.difference(self)) } } - /// Visit the values representing the intersection, + /// Visits the values representing the intersection, /// i.e. the values that are both in `self` and `other`. /// /// # Examples @@ -376,7 +384,7 @@ impl HashSet } } - /// Visit the values representing the union, + /// Visits the values representing the union, /// i.e. all the values in `self` or `other`, without duplicates. /// /// # Examples @@ -460,7 +468,7 @@ impl HashSet /// Returns `true` if the set contains a value. /// /// The value may be any borrowed form of the set's value type, but - /// `Hash` and `Eq` on the borrowed form *must* match those for + /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the value type. /// /// # Examples @@ -472,6 +480,9 @@ impl HashSet /// assert_eq!(set.contains(&1), true); /// assert_eq!(set.contains(&4), false); /// ``` + /// + /// [`Eq`]: ../../std/cmp/trait.Eq.html + /// [`Hash`]: ../../std/hash/trait.Hash.html #[stable(feature = "rust1", since = "1.0.0")] pub fn contains(&self, value: &Q) -> bool where T: Borrow, @@ -483,8 +494,11 @@ impl HashSet /// Returns a reference to the value in the set, if any, that is equal to the given value. /// /// The value may be any borrowed form of the set's value type, but - /// `Hash` and `Eq` on the borrowed form *must* match those for + /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the value type. + /// + /// [`Eq`]: ../../std/cmp/trait.Eq.html + /// [`Hash`]: ../../std/hash/trait.Hash.html #[stable(feature = "set_recovery", since = "1.9.0")] pub fn get(&self, value: &Q) -> Option<&T> where T: Borrow, @@ -596,7 +610,7 @@ impl HashSet /// present in the set. /// /// The value may be any borrowed form of the set's value type, but - /// `Hash` and `Eq` on the borrowed form *must* match those for + /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the value type. /// /// # Examples @@ -610,6 +624,9 @@ impl HashSet /// assert_eq!(set.remove(&2), true); /// assert_eq!(set.remove(&2), false); /// ``` + /// + /// [`Eq`]: ../../std/cmp/trait.Eq.html + /// [`Hash`]: ../../std/hash/trait.Hash.html #[stable(feature = "rust1", since = "1.0.0")] pub fn remove(&mut self, value: &Q) -> bool where T: Borrow, @@ -621,8 +638,11 @@ impl HashSet /// Removes and returns the value in the set, if any, that is equal to the given one. /// /// The value may be any borrowed form of the set's value type, but - /// `Hash` and `Eq` on the borrowed form *must* match those for + /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for /// the value type. + /// + /// [`Eq`]: ../../std/cmp/trait.Eq.html + /// [`Hash`]: ../../std/hash/trait.Hash.html #[stable(feature = "set_recovery", since = "1.9.0")] pub fn take(&mut self, value: &Q) -> Option where T: Borrow, @@ -856,25 +876,49 @@ impl<'a, 'b, T, S> Sub<&'b HashSet> for &'a HashSet } } -/// HashSet iterator +/// An iterator over the items of a `HashSet`. +/// +/// This `struct` is created by the [`iter`] method on [`HashSet`]. +/// See its documentation for more. +/// +/// [`HashSet`]: struct.HashSet.html +/// [`iter`]: struct.HashSet.html#method.iter #[stable(feature = "rust1", since = "1.0.0")] pub struct Iter<'a, K: 'a> { iter: Keys<'a, K, ()>, } -/// HashSet move iterator +/// An owning iterator over the items of a `HashSet`. +/// +/// This `struct` is created by the [`into_iter`] method on [`HashSet`] +/// (provided by the `IntoIterator` trait). See its documentation for more. +/// +/// [`HashSet`]: struct.HashSet.html +/// [`into_iter`]: struct.HashSet.html#method.into_iter #[stable(feature = "rust1", since = "1.0.0")] pub struct IntoIter { iter: map::IntoIter, } -/// HashSet drain iterator +/// A draining iterator over the items of a `HashSet`. +/// +/// This `struct` is created by the [`drain`] method on [`HashSet`]. +/// See its documentation for more. +/// +/// [`HashSet`]: struct.HashSet.html +/// [`drain`]: struct.HashSet.html#method.drain #[stable(feature = "rust1", since = "1.0.0")] pub struct Drain<'a, K: 'a> { iter: map::Drain<'a, K, ()>, } -/// Intersection iterator +/// A lazy iterator producing elements in the intersection of `HashSet`s. +/// +/// This `struct` is created by the [`intersection`] method on [`HashSet`]. +/// See its documentation for more. +/// +/// [`HashSet`]: struct.HashSet.html +/// [`intersection`]: struct.HashSet.html#method.intersection #[stable(feature = "rust1", since = "1.0.0")] pub struct Intersection<'a, T: 'a, S: 'a> { // iterator of the first set @@ -883,7 +927,13 @@ pub struct Intersection<'a, T: 'a, S: 'a> { other: &'a HashSet, } -/// Difference iterator +/// A lazy iterator producing elements in the difference of `HashSet`s. +/// +/// This `struct` is created by the [`difference`] method on [`HashSet`]. +/// See its documentation for more. +/// +/// [`HashSet`]: struct.HashSet.html +/// [`difference`]: struct.HashSet.html#method.difference #[stable(feature = "rust1", since = "1.0.0")] pub struct Difference<'a, T: 'a, S: 'a> { // iterator of the first set @@ -892,13 +942,25 @@ pub struct Difference<'a, T: 'a, S: 'a> { other: &'a HashSet, } -/// Symmetric difference iterator. +/// A lazy iterator producing elements in the symmetric difference of `HashSet`s. +/// +/// This `struct` is created by the [`symmetric_difference`] method on +/// [`HashSet`]. See its documentation for more. +/// +/// [`HashSet`]: struct.HashSet.html +/// [`symmetric_difference`]: struct.HashSet.html#method.symmetric_difference #[stable(feature = "rust1", since = "1.0.0")] pub struct SymmetricDifference<'a, T: 'a, S: 'a> { iter: Chain, Difference<'a, T, S>>, } -/// Set union iterator. +/// A lazy iterator producing elements in the union of `HashSet`s. +/// +/// This `struct` is created by the [`union`] method on [`HashSet`]. +/// See its documentation for more. +/// +/// [`HashSet`]: struct.HashSet.html +/// [`union`]: struct.HashSet.html#method.union #[stable(feature = "rust1", since = "1.0.0")] pub struct Union<'a, T: 'a, S: 'a> { iter: Chain, Difference<'a, T, S>>, diff --git a/src/libstd/collections/mod.rs b/src/libstd/collections/mod.rs index 8884d0688b8b7..506bf717337bd 100644 --- a/src/libstd/collections/mod.rs +++ b/src/libstd/collections/mod.rs @@ -157,29 +157,29 @@ //! information to do this itself. Therefore, it is up to us programmers to give //! it hints. //! -//! Any `with_capacity()` constructor will instruct the collection to allocate +//! Any `with_capacity` constructor will instruct the collection to allocate //! enough space for the specified number of elements. Ideally this will be for //! exactly that many elements, but some implementation details may prevent //! this. [`Vec`] and [`VecDeque`] can be relied on to allocate exactly the -//! requested amount, though. Use `with_capacity()` when you know exactly how many +//! requested amount, though. Use `with_capacity` when you know exactly how many //! elements will be inserted, or at least have a reasonable upper-bound on that //! number. //! -//! When anticipating a large influx of elements, the `reserve()` family of +//! When anticipating a large influx of elements, the `reserve` family of //! methods can be used to hint to the collection how much room it should make -//! for the coming items. As with `with_capacity()`, the precise behavior of +//! for the coming items. As with `with_capacity`, the precise behavior of //! these methods will be specific to the collection of interest. //! //! For optimal performance, collections will generally avoid shrinking //! themselves. If you believe that a collection will not soon contain any more -//! elements, or just really need the memory, the `shrink_to_fit()` method prompts +//! elements, or just really need the memory, the `shrink_to_fit` method prompts //! the collection to shrink the backing array to the minimum size capable of //! holding its elements. //! //! Finally, if ever you're interested in what the actual capacity of the -//! collection is, most collections provide a `capacity()` method to query this +//! collection is, most collections provide a `capacity` method to query this //! information on demand. This can be useful for debugging purposes, or for -//! use with the `reserve()` methods. +//! use with the `reserve` methods. //! //! ## Iterators //! @@ -194,11 +194,11 @@ //! //! All of the standard collections provide several iterators for performing //! bulk manipulation of their contents. The three primary iterators almost -//! every collection should provide are `iter()`, `iter_mut()`, and `into_iter()`. +//! every collection should provide are `iter`, `iter_mut`, and `into_iter`. //! Some of these are not provided on collections where it would be unsound or //! unreasonable to provide them. //! -//! `iter()` provides an iterator of immutable references to all the contents of a +//! `iter` provides an iterator of immutable references to all the contents of a //! collection in the most "natural" order. For sequence collections like [`Vec`], //! this means the items will be yielded in increasing order of index starting //! at 0. For ordered collections like [`BTreeMap`], this means that the items @@ -214,8 +214,8 @@ //! } //! ``` //! -//! `iter_mut()` provides an iterator of *mutable* references in the same order as -//! `iter()`. This is great for mutating all the contents of the collection. +//! `iter_mut` provides an iterator of *mutable* references in the same order as +//! `iter`. This is great for mutating all the contents of the collection. //! //! ``` //! let mut vec = vec![1, 2, 3, 4]; @@ -224,12 +224,12 @@ //! } //! ``` //! -//! `into_iter()` transforms the actual collection into an iterator over its +//! `into_iter` transforms the actual collection into an iterator over its //! contents by-value. This is great when the collection itself is no longer -//! needed, and the values are needed elsewhere. Using `extend()` with `into_iter()` +//! needed, and the values are needed elsewhere. Using `extend` with `into_iter` //! is the main way that contents of one collection are moved into another. -//! `extend()` automatically calls `into_iter()`, and takes any `T: `[`IntoIterator`]. -//! Calling `collect()` on an iterator itself is also a great way to convert one +//! `extend` automatically calls `into_iter`, and takes any `T: `[`IntoIterator`]. +//! Calling `collect` on an iterator itself is also a great way to convert one //! collection into another. Both of these methods should internally use the //! capacity management tools discussed in the previous section to do this as //! efficiently as possible. @@ -248,9 +248,9 @@ //! ``` //! //! Iterators also provide a series of *adapter* methods for performing common -//! threads to sequences. Among the adapters are functional favorites like `map()`, -//! `fold()`, `skip()` and `take()`. Of particular interest to collections is the -//! `rev()` adapter, that reverses any iterator that supports this operation. Most +//! threads to sequences. Among the adapters are functional favorites like `map`, +//! `fold`, `skip` and `take`. Of particular interest to collections is the +//! `rev` adapter, that reverses any iterator that supports this operation. Most //! collections provide reversible iterators as the way to iterate over them in //! reverse order. //! @@ -263,27 +263,27 @@ //! //! Several other collection methods also return iterators to yield a sequence //! of results but avoid allocating an entire collection to store the result in. -//! This provides maximum flexibility as `collect()` or `extend()` can be called to +//! This provides maximum flexibility as `collect` or `extend` can be called to //! "pipe" the sequence into any collection if desired. Otherwise, the sequence //! can be looped over with a `for` loop. The iterator can also be discarded //! after partial use, preventing the computation of the unused items. //! //! ## Entries //! -//! The `entry()` API is intended to provide an efficient mechanism for +//! The `entry` API is intended to provide an efficient mechanism for //! manipulating the contents of a map conditionally on the presence of a key or //! not. The primary motivating use case for this is to provide efficient //! accumulator maps. For instance, if one wishes to maintain a count of the //! number of times each key has been seen, they will have to perform some //! conditional logic on whether this is the first time the key has been seen or -//! not. Normally, this would require a `find()` followed by an `insert()`, +//! not. Normally, this would require a `find` followed by an `insert`, //! effectively duplicating the search effort on each insertion. //! //! When a user calls `map.entry(&key)`, the map will search for the key and //! then yield a variant of the `Entry` enum. //! //! If a `Vacant(entry)` is yielded, then the key *was not* found. In this case -//! the only valid operation is to `insert()` a value into the entry. When this is +//! the only valid operation is to `insert` a value into the entry. When this is //! done, the vacant entry is consumed and converted into a mutable reference to //! the value that was inserted. This allows for further manipulation of the //! value beyond the lifetime of the search itself. This is useful if complex @@ -291,14 +291,14 @@ //! just inserted. //! //! If an `Occupied(entry)` is yielded, then the key *was* found. In this case, -//! the user has several options: they can `get()`, `insert()` or `remove()` the +//! the user has several options: they can `get`, `insert` or `remove` the //! value of the occupied entry. Additionally, they can convert the occupied //! entry into a mutable reference to its value, providing symmetry to the -//! vacant `insert()` case. +//! vacant `insert` case. //! //! ### Examples //! -//! Here are the two primary ways in which `entry()` is used. First, a simple +//! Here are the two primary ways in which `entry` is used. First, a simple //! example where the logic performed on the values is trivial. //! //! #### Counting the number of times each character in a string occurs @@ -322,7 +322,7 @@ //! ``` //! //! When the logic to be performed on the value is more complex, we may simply -//! use the `entry()` API to ensure that the value is initialized and perform the +//! use the `entry` API to ensure that the value is initialized and perform the //! logic afterwards. //! //! #### Tracking the inebriation of customers at a bar @@ -360,7 +360,7 @@ //! //! # Insert and complex keys //! -//! If we have a more complex key, calls to `insert()` will +//! If we have a more complex key, calls to `insert` will //! not update the value of the key. For example: //! //! ``` @@ -442,16 +442,14 @@ mod hash; #[stable(feature = "rust1", since = "1.0.0")] pub mod hash_map { - //! A hash map implementation which uses linear probing with Robin - //! Hood bucket stealing. + //! A hash map implemented with linear probing and Robin Hood bucket stealing. #[stable(feature = "rust1", since = "1.0.0")] pub use super::hash::map::*; } #[stable(feature = "rust1", since = "1.0.0")] pub mod hash_set { - //! An implementation of a hash set using the underlying representation of a - //! HashMap where the value is (). + //! A hash set implemented as a `HashMap` where the value is `()`. #[stable(feature = "rust1", since = "1.0.0")] pub use super::hash::set::*; } diff --git a/src/tools/linkchecker/main.rs b/src/tools/linkchecker/main.rs index 8c4eb728b7561..137de561c76c9 100644 --- a/src/tools/linkchecker/main.rs +++ b/src/tools/linkchecker/main.rs @@ -142,7 +142,8 @@ fn check(cache: &mut Cache, if file.ends_with("btree_set/struct.BTreeSet.html") || file.ends_with("collections/struct.BTreeSet.html") || file.ends_with("collections/btree_map/struct.BTreeMap.html") || - file.ends_with("collections/hash_map/struct.HashMap.html") { + file.ends_with("collections/hash_map/struct.HashMap.html") || + file.ends_with("collections/hash_set/struct.HashSet.html") { return None; }