From 89ac8654e19b123132c82eb9f81ed3ba9bb3eb33 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Thu, 13 Apr 2017 22:48:49 +0200 Subject: [PATCH] Various consistency and phrasing fixes in std::collections' docs * Changed btree_map's and hash_map's Entry (etc.) docs to be consistent * Changed VecDeque's type and module summary sentences to be consistent with each other as well as with other summary sentences in the module * Changed HashMap's and HashSet's summary sentences to be less redundantly phrased and also more consistant with the other summary sentences in the module * Also, added an example to Bound --- src/libcollections/btree/map.rs | 13 ++++++++----- src/libcollections/lib.rs | 17 +++++++++++++++++ src/libcollections/vec_deque.rs | 6 ++---- src/libstd/collections/hash/map.rs | 16 ++++++++-------- src/libstd/collections/hash/set.rs | 3 +-- src/libstd/collections/mod.rs | 6 ++---- 6 files changed, 38 insertions(+), 23 deletions(-) diff --git a/src/libcollections/btree/map.rs b/src/libcollections/btree/map.rs index e7e91a2fcaad..b986c0275502 100644 --- a/src/libcollections/btree/map.rs +++ b/src/libcollections/btree/map.rs @@ -420,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>), @@ -451,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")] @@ -473,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/lib.rs b/src/libcollections/lib.rs index 99afd08e8118..4ff54095bd35 100644 --- a/src/libcollections/lib.rs +++ b/src/libcollections/lib.rs @@ -135,6 +135,23 @@ mod std { } /// An endpoint of a range of keys. +/// # Examples +/// +/// ``` +/// 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()); +/// ``` #[stable(feature = "collections_bound", since = "1.17.0")] #[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)] pub enum Bound { diff --git a/src/libcollections/vec_deque.rs b/src/libcollections/vec_deque.rs index 7b8f4f4c6c82..2ce3b92843bd 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,8 +42,7 @@ 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`] diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs index 9e71ec1d25df..eacb59d375a5 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 @@ -1511,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>), @@ -1547,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 @@ -1567,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 diff --git a/src/libstd/collections/hash/set.rs b/src/libstd/collections/hash/set.rs index e56470c617f8..e3fad2850257 100644 --- a/src/libstd/collections/hash/set.rs +++ b/src/libstd/collections/hash/set.rs @@ -24,8 +24,7 @@ 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 diff --git a/src/libstd/collections/mod.rs b/src/libstd/collections/mod.rs index 73acf69c72cd..506bf717337b 100644 --- a/src/libstd/collections/mod.rs +++ b/src/libstd/collections/mod.rs @@ -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::*; }