Skip to content

Commit 5f13a3b

Browse files
committed
Auto merge of #41286 - lukaramu:std-collections-docs, r=frewsxcv
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
2 parents be1a74e + 2a23e6e commit 5f13a3b

File tree

10 files changed

+415
-146
lines changed

10 files changed

+415
-146
lines changed

src/libcollections/binary_heap.rs

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,12 @@
2020
//!
2121
//! This is a larger example that implements [Dijkstra's algorithm][dijkstra]
2222
//! to solve the [shortest path problem][sssp] on a [directed graph][dir_graph].
23-
//! It shows how to use `BinaryHeap` with custom types.
23+
//! It shows how to use [`BinaryHeap`] with custom types.
2424
//!
2525
//! [dijkstra]: http://en.wikipedia.org/wiki/Dijkstra%27s_algorithm
2626
//! [sssp]: http://en.wikipedia.org/wiki/Shortest_path_problem
2727
//! [dir_graph]: http://en.wikipedia.org/wiki/Directed_graph
28+
//! [`BinaryHeap`]: struct.BinaryHeap.html
2829
//!
2930
//! ```
3031
//! use std::cmp::Ordering;
@@ -218,10 +219,14 @@ pub struct BinaryHeap<T> {
218219
data: Vec<T>,
219220
}
220221

221-
/// A container object that represents the result of the [`peek_mut`] method
222-
/// on `BinaryHeap`. See its documentation for details.
222+
/// Structure wrapping a mutable reference to the greatest item on a
223+
/// `BinaryHeap`.
224+
///
225+
/// This `struct` is created by the [`peek_mut`] method on [`BinaryHeap`]. See
226+
/// its documentation for more.
223227
///
224228
/// [`peek_mut`]: struct.BinaryHeap.html#method.peek_mut
229+
/// [`BinaryHeap`]: struct.BinaryHeap.html
225230
#[stable(feature = "binary_heap_peek_mut", since = "1.12.0")]
226231
pub struct PeekMut<'a, T: 'a + Ord> {
227232
heap: &'a mut BinaryHeap<T>,
@@ -434,7 +439,7 @@ impl<T: Ord> BinaryHeap<T> {
434439
/// given `BinaryHeap`. Does nothing if the capacity is already sufficient.
435440
///
436441
/// Note that the allocator may give the collection more space than it requests. Therefore
437-
/// capacity can not be relied upon to be precisely minimal. Prefer `reserve` if future
442+
/// capacity can not be relied upon to be precisely minimal. Prefer [`reserve`] if future
438443
/// insertions are expected.
439444
///
440445
/// # Panics
@@ -452,6 +457,8 @@ impl<T: Ord> BinaryHeap<T> {
452457
/// assert!(heap.capacity() >= 100);
453458
/// heap.push(4);
454459
/// ```
460+
///
461+
/// [`reserve`]: #method.reserve
455462
#[stable(feature = "rust1", since = "1.0.0")]
456463
pub fn reserve_exact(&mut self, additional: usize) {
457464
self.data.reserve_exact(additional);
@@ -971,7 +978,13 @@ impl<'a, T> Drop for Hole<'a, T> {
971978
}
972979
}
973980

974-
/// `BinaryHeap` iterator.
981+
/// An iterator over the elements of a `BinaryHeap`.
982+
///
983+
/// This `struct` is created by the [`iter`] method on [`BinaryHeap`]. See its
984+
/// documentation for more.
985+
///
986+
/// [`iter`]: struct.BinaryHeap.html#method.iter
987+
/// [`BinaryHeap`]: struct.BinaryHeap.html
975988
#[stable(feature = "rust1", since = "1.0.0")]
976989
pub struct Iter<'a, T: 'a> {
977990
iter: slice::Iter<'a, T>,
@@ -1027,7 +1040,13 @@ impl<'a, T> ExactSizeIterator for Iter<'a, T> {
10271040
#[unstable(feature = "fused", issue = "35602")]
10281041
impl<'a, T> FusedIterator for Iter<'a, T> {}
10291042

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

1079-
/// An iterator that drains a `BinaryHeap`.
1098+
/// A draining iterator over the elements of a `BinaryHeap`.
1099+
///
1100+
/// This `struct` is created by the [`drain`] method on [`BinaryHeap`]. See its
1101+
/// documentation for more.
1102+
///
1103+
/// [`drain`]: struct.BinaryHeap.html#method.drain
1104+
/// [`BinaryHeap`]: struct.BinaryHeap.html
10801105
#[stable(feature = "drain", since = "1.6.0")]
10811106
#[derive(Debug)]
10821107
pub struct Drain<'a, T: 'a> {

src/libcollections/btree/map.rs

Lines changed: 64 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -262,7 +262,13 @@ impl<K, Q: ?Sized> super::Recover<Q> for BTreeMap<K, ()>
262262
}
263263
}
264264

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

279-
/// A mutable iterator over a `BTreeMap`'s entries.
285+
/// A mutable iterator over the entries of a `BTreeMap`.
286+
///
287+
/// This `struct` is created by the [`iter_mut`] method on [`BTreeMap`]. See its
288+
/// documentation for more.
289+
///
290+
/// [`iter_mut`]: struct.BTreeMap.html#method.iter_mut
291+
/// [`BTreeMap`]: struct.BTreeMap.html
280292
#[stable(feature = "rust1", since = "1.0.0")]
281293
#[derive(Debug)]
282294
pub struct IterMut<'a, K: 'a, V: 'a> {
283295
range: RangeMut<'a, K, V>,
284296
length: usize,
285297
}
286298

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

306-
/// An iterator over a `BTreeMap`'s keys.
324+
/// An iterator over the keys of a `BTreeMap`.
325+
///
326+
/// This `struct` is created by the [`keys`] method on [`BTreeMap`]. See its
327+
/// documentation for more.
328+
///
329+
/// [`keys`]: struct.BTreeMap.html#method.keys
330+
/// [`BTreeMap`]: struct.BTreeMap.html
307331
#[stable(feature = "rust1", since = "1.0.0")]
308332
pub struct Keys<'a, K: 'a, V: 'a> {
309333
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> {
316340
}
317341
}
318342

319-
/// An iterator over a `BTreeMap`'s values.
343+
/// An iterator over the values of a `BTreeMap`.
344+
///
345+
/// This `struct` is created by the [`values`] method on [`BTreeMap`]. See its
346+
/// documentation for more.
347+
///
348+
/// [`values`]: struct.BTreeMap.html#method.values
349+
/// [`BTreeMap`]: struct.BTreeMap.html
320350
#[stable(feature = "rust1", since = "1.0.0")]
321351
pub struct Values<'a, K: 'a, V: 'a> {
322352
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>
329359
}
330360
}
331361

332-
/// A mutable iterator over a `BTreeMap`'s values.
362+
/// A mutable iterator over the values of a `BTreeMap`.
363+
///
364+
/// This `struct` is created by the [`values_mut`] method on [`BTreeMap`]. See its
365+
/// documentation for more.
366+
///
367+
/// [`values_mut`]: struct.BTreeMap.html#method.values_mut
368+
/// [`BTreeMap`]: struct.BTreeMap.html
333369
#[stable(feature = "map_values_mut", since = "1.10.0")]
334370
#[derive(Debug)]
335371
pub struct ValuesMut<'a, K: 'a, V: 'a> {
336372
inner: IterMut<'a, K, V>,
337373
}
338374

339-
/// An iterator over a sub-range of `BTreeMap`'s entries.
375+
/// An iterator over a sub-range of entries in a `BTreeMap`.
376+
///
377+
/// This `struct` is created by the [`range`] method on [`BTreeMap`]. See its
378+
/// documentation for more.
379+
///
380+
/// [`range`]: struct.BTreeMap.html#method.range
381+
/// [`BTreeMap`]: struct.BTreeMap.html
340382
#[stable(feature = "btree_range", since = "1.17.0")]
341383
pub struct Range<'a, K: 'a, V: 'a> {
342384
front: Handle<NodeRef<marker::Immut<'a>, 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>
350392
}
351393
}
352394

353-
/// A mutable iterator over a sub-range of `BTreeMap`'s entries.
395+
/// A mutable iterator over a sub-range of entries in a `BTreeMap`.
396+
///
397+
/// This `struct` is created by the [`range_mut`] method on [`BTreeMap`]. See its
398+
/// documentation for more.
399+
///
400+
/// [`range_mut`]: struct.BTreeMap.html#method.range_mut
401+
/// [`BTreeMap`]: struct.BTreeMap.html
354402
#[stable(feature = "btree_range", since = "1.17.0")]
355403
pub struct RangeMut<'a, K: 'a, V: 'a> {
356404
front: Handle<NodeRef<marker::Mut<'a>, 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,
372420
}
373421

374422
/// A view into a single entry in a map, which may either be vacant or occupied.
375-
/// This enum is constructed from the [`entry`] method on [`BTreeMap`].
423+
///
424+
/// This `enum` is constructed from the [`entry`] method on [`BTreeMap`].
376425
///
377426
/// [`BTreeMap`]: struct.BTreeMap.html
378427
/// [`entry`]: struct.BTreeMap.html#method.entry
379428
#[stable(feature = "rust1", since = "1.0.0")]
380429
pub enum Entry<'a, K: 'a, V: 'a> {
381-
/// A vacant `Entry`
430+
/// A vacant entry.
382431
#[stable(feature = "rust1", since = "1.0.0")]
383432
Vacant(#[stable(feature = "rust1", since = "1.0.0")]
384433
VacantEntry<'a, K, V>),
385434

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

406-
/// A vacant `Entry`. It is part of the [`Entry`] enum.
455+
/// A view into a vacant entry in a `BTreeMap`.
456+
/// It is part of the [`Entry`] enum.
407457
///
408458
/// [`Entry`]: enum.Entry.html
409459
#[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> {
425475
}
426476
}
427477

428-
/// An occupied `Entry`. It is part of the [`Entry`] enum.
478+
/// A view into an occupied entry in a `BTreeMap`.
479+
/// It is part of the [`Entry`] enum.
429480
///
430481
/// [`Entry`]: enum.Entry.html
431482
#[stable(feature = "rust1", since = "1.0.0")]

src/libcollections/btree/set.rs

Lines changed: 23 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -74,9 +74,10 @@ pub struct BTreeSet<T> {
7474
map: BTreeMap<T, ()>,
7575
}
7676

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

97-
/// An owning iterator over a `BTreeSet`'s items.
98+
/// An owning iterator over the items of a `BTreeSet`.
9899
///
99-
/// This structure is created by the `into_iter` method on [`BTreeSet`]
100-
/// [`BTreeSet`] (provided by the `IntoIterator` trait).
100+
/// This `struct` is created by the [`into_iter`] method on [`BTreeSet`]
101+
/// (provided by the `IntoIterator` trait). See its documentation for more.
101102
///
102103
/// [`BTreeSet`]: struct.BTreeSet.html
104+
/// [`into_iter`]: struct.BTreeSet.html#method.into_iter
103105
#[stable(feature = "rust1", since = "1.0.0")]
104106
#[derive(Debug)]
105107
pub struct IntoIter<T> {
106108
iter: ::btree_map::IntoIter<T, ()>,
107109
}
108110

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

121-
/// A lazy iterator producing elements in the set difference (in-order).
124+
/// A lazy iterator producing elements in the difference of `BTreeSet`s.
122125
///
123-
/// This structure is created by the [`difference`] method on [`BTreeSet`].
126+
/// This `struct` is created by the [`difference`] method on [`BTreeSet`].
127+
/// See its documentation for more.
124128
///
125129
/// [`BTreeSet`]: struct.BTreeSet.html
126130
/// [`difference`]: struct.BTreeSet.html#method.difference
@@ -139,10 +143,10 @@ impl<'a, T: 'a + fmt::Debug> fmt::Debug for Difference<'a, T> {
139143
}
140144
}
141145

142-
/// A lazy iterator producing elements in the set symmetric difference (in-order).
146+
/// A lazy iterator producing elements in the symmetric difference of `BTreeSet`s.
143147
///
144-
/// This structure is created by the [`symmetric_difference`] method on
145-
/// [`BTreeSet`].
148+
/// This `struct` is created by the [`symmetric_difference`] method on
149+
/// [`BTreeSet`]. See its documentation for more.
146150
///
147151
/// [`BTreeSet`]: struct.BTreeSet.html
148152
/// [`symmetric_difference`]: struct.BTreeSet.html#method.symmetric_difference
@@ -161,9 +165,10 @@ impl<'a, T: 'a + fmt::Debug> fmt::Debug for SymmetricDifference<'a, T> {
161165
}
162166
}
163167

164-
/// A lazy iterator producing elements in the set intersection (in-order).
168+
/// A lazy iterator producing elements in the intersection of `BTreeSet`s.
165169
///
166-
/// This structure is created by the [`intersection`] method on [`BTreeSet`].
170+
/// This `struct` is created by the [`intersection`] method on [`BTreeSet`].
171+
/// See its documentation for more.
167172
///
168173
/// [`BTreeSet`]: struct.BTreeSet.html
169174
/// [`intersection`]: struct.BTreeSet.html#method.intersection
@@ -182,9 +187,10 @@ impl<'a, T: 'a + fmt::Debug> fmt::Debug for Intersection<'a, T> {
182187
}
183188
}
184189

185-
/// A lazy iterator producing elements in the set union (in-order).
190+
/// A lazy iterator producing elements in the union of `BTreeSet`s.
186191
///
187-
/// This structure is created by the [`union`] method on [`BTreeSet`].
192+
/// This `struct` is created by the [`union`] method on [`BTreeSet`].
193+
/// See its documentation for more.
188194
///
189195
/// [`BTreeSet`]: struct.BTreeSet.html
190196
/// [`union`]: struct.BTreeSet.html#method.union
@@ -728,7 +734,7 @@ impl<T> IntoIterator for BTreeSet<T> {
728734
type Item = T;
729735
type IntoIter = IntoIter<T>;
730736

731-
/// Gets an iterator for moving out the BtreeSet's contents.
737+
/// Gets an iterator for moving out the `BTreeSet`'s contents.
732738
///
733739
/// # Examples
734740
///

0 commit comments

Comments
 (0)