From 2281290b3def8b283418a9a238b931b5d60b99ad Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sat, 4 Feb 2017 00:59:28 +0100 Subject: [PATCH] Add missing urls and small nits --- src/libcollections/vec_deque.rs | 83 +++++++++++++++++++++++---------- src/libstd/collections/mod.rs | 10 +++- 2 files changed, 66 insertions(+), 27 deletions(-) diff --git a/src/libcollections/vec_deque.rs b/src/libcollections/vec_deque.rs index 5e1adb3d808ce..2ce5e04a8a132 100644 --- a/src/libcollections/vec_deque.rs +++ b/src/libcollections/vec_deque.rs @@ -46,10 +46,15 @@ const MAXIMUM_ZST_CAPACITY: usize = 1 << (64 - 1); // Largest possible power of /// `VecDeque` is a growable ring buffer, which can be used as a double-ended /// queue efficiently. /// -/// 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 @@ -92,13 +97,13 @@ impl Default for VecDeque { } impl VecDeque { - /// Marginally more convenient + /// Marginally more convenient. #[inline] fn ptr(&self) -> *mut T { self.buf.ptr() } - /// Marginally more convenient + /// Marginally more convenient. #[inline] fn cap(&self) -> usize { if mem::size_of::() == 0 { @@ -109,19 +114,19 @@ impl VecDeque { } } - /// Turn ptr into a slice + /// Turn ptr into a slice. #[inline] unsafe fn buffer_as_slice(&self) -> &[T] { slice::from_raw_parts(self.ptr(), self.cap()) } - /// Turn ptr into a mut slice + /// Turn ptr into a mut slice. #[inline] unsafe fn buffer_as_mut_slice(&mut self) -> &mut [T] { slice::from_raw_parts_mut(self.ptr(), self.cap()) } - /// Moves an element out of the buffer + /// Moves an element out of the buffer. #[inline] unsafe fn buffer_read(&mut self, off: usize) -> T { ptr::read(self.ptr().offset(off as isize)) @@ -133,7 +138,7 @@ impl VecDeque { ptr::write(self.ptr().offset(off as isize), value); } - /// Returns true if and only if the buffer is at capacity + /// Returns true if and only if the buffer is at capacity. #[inline] fn is_full(&self) -> bool { self.cap() - self.len() == 1 @@ -506,12 +511,15 @@ 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 /// - /// Panics if the new capacity overflows `usize`. + /// Panics if the new capacity overflows [`usize`]. + /// + /// [`reserve`]: #method.reserve + /// [`usize`]: ../../std/primitive.usize.html /// /// # Examples /// @@ -532,7 +540,9 @@ impl VecDeque { /// /// # Panics /// - /// Panics if the new capacity overflows `usize`. + /// Panics if the new capacity overflows [`usize`]. + /// + /// [`usize`]: ../../std/primitive.usize.html /// /// # Examples /// @@ -788,7 +798,7 @@ impl VecDeque { count(self.tail, self.head, self.cap()) } - /// Returns true if the buffer contains no elements + /// Returns true if the buffer contains no elements. /// /// # Examples /// @@ -812,14 +822,17 @@ impl VecDeque { /// consumed until the end. /// /// Note 2: It is unspecified how many elements are removed from the deque, - /// if the `Drain` value is not dropped, but the borrow it holds expires - /// (eg. due to mem::forget). + /// if the [`Drain`] value is not dropped, but the borrow it holds expires + /// (eg. due to [`mem::forget`]). /// /// # Panics /// /// Panics if the starting point is greater than the end point or if /// the end point is greater than the length of the vector. /// + /// [`Drain`]: ../../std/collections/vec_deque/struct.Drain.html + /// [`mem::forget`]: ../../std/mem/fn.forget.html + /// /// # Examples /// /// ``` @@ -941,9 +954,11 @@ impl VecDeque { a.contains(x) || b.contains(x) } - /// Provides a reference to the front element, or `None` if the sequence is + /// Provides a reference to the front element, or [`None`] if the sequence is /// empty. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// ``` @@ -965,9 +980,11 @@ impl VecDeque { } } - /// Provides a mutable reference to the front element, or `None` if the + /// Provides a mutable reference to the front element, or [`None`] if the /// sequence is empty. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// ``` @@ -993,9 +1010,11 @@ impl VecDeque { } } - /// Provides a reference to the back element, or `None` if the sequence is + /// Provides a reference to the back element, or [`None`] if the sequence is /// empty. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// ``` @@ -1017,9 +1036,11 @@ impl VecDeque { } } - /// Provides a mutable reference to the back element, or `None` if the + /// Provides a mutable reference to the back element, or [`None`] if the /// sequence is empty. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// ``` @@ -1046,9 +1067,11 @@ impl VecDeque { } } - /// Removes the first element and returns it, or `None` if the sequence is + /// Removes the first element and returns it, or [`None`] if the sequence is /// empty. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// ``` @@ -1131,9 +1154,11 @@ impl VecDeque { unsafe { self.buffer_write(head, value) } } - /// Removes the last element from a buffer and returns it, or `None` if + /// Removes the last element from a buffer and returns it, or [`None`] if /// it is empty. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// ``` @@ -1166,10 +1191,12 @@ impl VecDeque { /// /// This does not preserve ordering, but is O(1). /// - /// Returns `None` if `index` is out of bounds. + /// Returns [`None`] if `index` is out of bounds. /// /// Element at index 0 is the front of the queue. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// ``` @@ -1201,10 +1228,12 @@ impl VecDeque { /// /// This does not preserve ordering, but is O(1). /// - /// Returns `None` if `index` is out of bounds. + /// Returns [`None`] if `index` is out of bounds. /// /// Element at index 0 is the front of the queue. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// ``` @@ -1238,7 +1267,7 @@ impl VecDeque { /// /// # Panics /// - /// Panics if `index` is greater than `VecDeque`'s length + /// Panics if `index` is greater than `VecDeque`'s length. /// /// # Examples /// @@ -1463,10 +1492,12 @@ impl VecDeque { /// Removes and returns the element at `index` from the `VecDeque`. /// Whichever end is closer to the removal point will be moved to make /// room, and all the affected elements will be moved to new positions. - /// Returns `None` if `index` is out of bounds. + /// Returns [`None`] if `index` is out of bounds. /// /// Element at index 0 is the front of the queue. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// ``` @@ -1709,7 +1740,9 @@ impl VecDeque { /// /// # Panics /// - /// Panics if the new number of elements in self overflows a `usize`. + /// Panics if the new number of elements in self overflows a [`usize`]. + /// + /// [`usize`]: ../../std/primitive.usize.html /// /// # Examples /// diff --git a/src/libstd/collections/mod.rs b/src/libstd/collections/mod.rs index b9e92a01b2f8e..e2b273cc90465 100644 --- a/src/libstd/collections/mod.rs +++ b/src/libstd/collections/mod.rs @@ -20,7 +20,7 @@ //! processing. They are exceptionally good at doing what they do. All the other //! collections in the standard library have specific use cases where they are //! the optimal choice, but these cases are borderline *niche* in comparison. -//! Even when `Vec` and `HashMap` are technically suboptimal, they're probably a +//! Even when [`Vec`] and [`HashMap`] are technically suboptimal, they're probably a //! good enough choice to get started. //! //! Rust's collections can be grouped into four major categories: @@ -37,6 +37,7 @@ //! individual collections can be found on their own documentation pages. //! //! ### Use a `Vec` when: +//! //! * You want to collect items up to be processed or sent elsewhere later, and //! don't care about any properties of the actual values being stored. //! * You want a sequence of elements in a particular order, and will only be @@ -46,12 +47,14 @@ //! * You want a heap-allocated array. //! //! ### Use a `VecDeque` when: +//! //! * You want a [`Vec`] that supports efficient insertion at both ends of the //! sequence. //! * You want a queue. //! * You want a double-ended queue (deque). //! //! ### Use a `LinkedList` when: +//! //! * You want a [`Vec`] or [`VecDeque`] of unknown size, and can't tolerate //! amortization. //! * You want to efficiently split and append lists. @@ -59,11 +62,13 @@ //! list. //! //! ### Use a `HashMap` when: +//! //! * You want to associate arbitrary keys with an arbitrary value. //! * You want a cache. //! * You want a map, with no extra functionality. //! //! ### Use a `BTreeMap` when: +//! //! * You're interested in what the smallest or largest key-value pair is. //! * You want to find the largest or smallest key that is smaller or larger //! than something. @@ -71,6 +76,7 @@ //! * You want a sorted map. //! //! ### Use the `Set` variant of any of these `Map`s when: +//! //! * You just want to remember which keys you've seen. //! * There is no meaningful value to associate with your keys. //! * You just want a set. @@ -451,7 +457,7 @@ pub mod 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 (). + //! `HashMap` where the value is (). #[stable(feature = "rust1", since = "1.0.0")] pub use super::hash::set::*; }