Various fixes to wording consistency in the docs

Author: Stjepan Glavina

src/libcollections/binary_heap.rs

@@ -930,13 +930,13 @@ impl<'a, T> Hole<'a, T> {
         self.pos
     }
 
-    /// Return a reference to the element removed
+    /// Returns a reference to the element removed.
     #[inline]
     fn element(&self) -> &T {
         self.elt.as_ref().unwrap()
     }
 
-    /// Return a reference to the element at `index`.
+    /// Returns a reference to the element at `index`.
     ///
     /// Unsafe because index must be within the data slice and not equal to pos.
     #[inline]

src/libcollections/btree/map.rs

@@ -526,7 +526,7 @@ impl<K: Ord, V> BTreeMap<K, V> {
         }
     }
 
-    /// Returns true if the map contains a value for the specified key.
+    /// Returns `true` if the map contains a value for the specified key.
     ///
     /// The key may be any borrowed form of the map's key type, but the ordering
     /// on the borrowed form *must* match the ordering on the key type.
@@ -1965,7 +1965,7 @@ impl<K, V> BTreeMap<K, V> {
         self.length
     }
 
-    /// Returns true if the map contains no elements.
+    /// Returns `true` if the map contains no elements.
     ///
     /// # Examples
     ///

src/libcollections/btree/set.rs

@@ -415,7 +415,7 @@ impl<T: Ord> BTreeSet<T> {
         self.map.len()
     }
 
-    /// Returns true if the set contains no elements.
+    /// Returns `true` if the set contains no elements.
     ///
     /// # Examples
     ///

src/libcollections/enum_set.rs

@@ -106,7 +106,7 @@ impl<E: CLike> EnumSet<E> {
         self.bits.count_ones() as usize
     }
 
-    /// Returns true if the `EnumSet` is empty.
+    /// Returns `true` if the `EnumSet` is empty.
     pub fn is_empty(&self) -> bool {
         self.bits == 0
     }

src/libcollections/range.rs

@@ -20,9 +20,9 @@ use Bound::{self, Excluded, Included, Unbounded};
 /// **RangeArgument** is implemented by Rust's built-in range types, produced
 /// by range syntax like `..`, `a..`, `..b` or `c..d`.
 pub trait RangeArgument<T: ?Sized> {
-    /// Start index bound
+    /// Start index bound.
     ///
-    /// Return start value as a `Bound`
+    /// Returns start value as a `Bound`.
     ///
     /// # Examples
     ///
@@ -42,9 +42,9 @@ pub trait RangeArgument<T: ?Sized> {
     /// ```
     fn start(&self) -> Bound<&T>;
 
-    /// End index bound
+    /// End index bound.
     ///
-    /// Return end value as a `Bound`
+    /// Returns end value as a `Bound`.
     ///
     /// # Examples
     ///

src/libcollections/slice.rs

@@ -195,7 +195,7 @@ impl<T> [T] {
         core_slice::SliceExt::is_empty(self)
     }
 
-    /// Returns the first element of a slice, or `None` if it is empty.
+    /// Returns the first element of the slice, or `None` if it is empty.
     ///
     /// # Examples
     ///
@@ -212,7 +212,7 @@ impl<T> [T] {
         core_slice::SliceExt::first(self)
     }
 
-    /// Returns a mutable pointer to the first element of a slice, or `None` if it is empty.
+    /// Returns a mutable pointer to the first element of the slice, or `None` if it is empty.
     ///
     /// # Examples
     ///
@@ -230,7 +230,7 @@ impl<T> [T] {
         core_slice::SliceExt::first_mut(self)
     }
 
-    /// Returns the first and all the rest of the elements of a slice, or `None` if it is empty.
+    /// Returns the first and all the rest of the elements of the slice, or `None` if it is empty.
     ///
     /// # Examples
     ///
@@ -248,7 +248,7 @@ impl<T> [T] {
         core_slice::SliceExt::split_first(self)
     }
 
-    /// Returns the first and all the rest of the elements of a slice, or `None` if it is empty.
+    /// Returns the first and all the rest of the elements of the slice, or `None` if it is empty.
     ///
     /// # Examples
     ///
@@ -268,7 +268,7 @@ impl<T> [T] {
         core_slice::SliceExt::split_first_mut(self)
     }
 
-    /// Returns the last and all the rest of the elements of a slice, or `None` if it is empty.
+    /// Returns the last and all the rest of the elements of the slice, or `None` if it is empty.
     ///
     /// # Examples
     ///
@@ -287,7 +287,7 @@ impl<T> [T] {
 
     }
 
-    /// Returns the last and all the rest of the elements of a slice, or `None` if it is empty.
+    /// Returns the last and all the rest of the elements of the slice, or `None` if it is empty.
     ///
     /// # Examples
     ///
@@ -307,7 +307,7 @@ impl<T> [T] {
         core_slice::SliceExt::split_last_mut(self)
     }
 
-    /// Returns the last element of a slice, or `None` if it is empty.
+    /// Returns the last element of the slice, or `None` if it is empty.
     ///
     /// # Examples
     ///
@@ -485,7 +485,7 @@ impl<T> [T] {
         core_slice::SliceExt::as_mut_ptr(self)
     }
 
-    /// Swaps two elements in a slice.
+    /// Swaps two elements in the slice.
     ///
     /// # Arguments
     ///
@@ -509,7 +509,7 @@ impl<T> [T] {
         core_slice::SliceExt::swap(self, a, b)
     }
 
-    /// Reverses the order of elements in a slice, in place.
+    /// Reverses the order of elements in the slice, in place.
     ///
     /// # Example
     ///
@@ -955,7 +955,7 @@ impl<T> [T] {
         core_slice::SliceExt::ends_with(self, needle)
     }
 
-    /// Binary search a sorted slice for a given element.
+    /// Binary searches this sorted slice for a given element.
     ///
     /// If the value is found then `Ok` is returned, containing the
     /// index of the matching element; if the value is not found then
@@ -984,7 +984,7 @@ impl<T> [T] {
         core_slice::SliceExt::binary_search(self, x)
     }
 
-    /// Binary search a sorted slice with a comparator function.
+    /// Binary searches this sorted slice with a comparator function.
     ///
     /// The comparator function should implement an order consistent
     /// with the sort order of the underlying slice, returning an
@@ -1023,7 +1023,7 @@ impl<T> [T] {
         core_slice::SliceExt::binary_search_by(self, f)
     }
 
-    /// Binary search a sorted slice with a key extraction function.
+    /// Binary searches this sorted slice with a key extraction function.
     ///
     /// Assumes that the slice is sorted by the key, for instance with
     /// [`sort_by_key`] using the same key extraction function.
@@ -1092,7 +1092,7 @@ impl<T> [T] {
         merge_sort(self, |a, b| a.lt(b));
     }
 
-    /// Sorts the slice using `compare` to compare elements.
+    /// Sorts the slice with a comparator function.
     ///
     /// This sort is stable (i.e. does not reorder equal elements) and `O(n log n)` worst-case.
     ///
@@ -1125,7 +1125,7 @@ impl<T> [T] {
         merge_sort(self, |a, b| compare(a, b) == Less);
     }
 
-    /// Sorts the slice using `f` to extract a key to compare elements by.
+    /// Sorts the slice with a key extraction function.
     ///
     /// This sort is stable (i.e. does not reorder equal elements) and `O(n log n)` worst-case.
     ///
@@ -1191,8 +1191,8 @@ impl<T> [T] {
         core_slice::SliceExt::sort_unstable(self);
     }
 
-    /// Sorts the slice using `compare` to compare elements, but may not preserve the order of
-    /// equal elements.
+    /// Sorts the slice with a comparator function, but may not preserve the order of equal
+    /// elements.
     ///
     /// This sort is unstable (i.e. may reorder equal elements), in-place (i.e. does not allocate),
     /// and `O(n log n)` worst-case.
@@ -1231,8 +1231,8 @@ impl<T> [T] {
         core_slice::SliceExt::sort_unstable_by(self, compare);
     }
 
-    /// Sorts the slice using `f` to extract a key to compare elements by, but may not preserve the
-    /// order of equal elements.
+    /// Sorts the slice with a key extraction function, but may not preserve the order of equal
+    /// elements.
     ///
     /// This sort is unstable (i.e. may reorder equal elements), in-place (i.e. does not allocate),
     /// and `O(n log n)` worst-case.
@@ -1313,7 +1313,6 @@ impl<T> [T] {
         core_slice::SliceExt::copy_from_slice(self, src)
     }
 
-
     /// Copies `self` into a new `Vec`.
     ///
     /// # Examples

src/libcollections/str.rs

@@ -204,7 +204,7 @@ impl str {
         core_str::StrExt::len(self)
     }
 
-    /// Returns true if this slice has a length of zero bytes.
+    /// Returns `true` if `self` has a length of zero bytes.
     ///
     /// # Examples
     ///

src/libcollections/vec_deque.rs

@@ -133,7 +133,7 @@ impl<T> VecDeque<T> {
         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 full capacity.
     #[inline]
     fn is_full(&self) -> bool {
         self.cap() - self.len() == 1
@@ -788,7 +788,7 @@ impl<T> VecDeque<T> {
         count(self.tail, self.head, self.cap())
     }
 
-    /// Returns true if the buffer contains no elements
+    /// Returns `true` if the `VecDeque` is empty.
     ///
     /// # Examples
     ///

src/libcore/any.rs

@@ -137,7 +137,7 @@ impl fmt::Debug for Any + Send {
 }
 
 impl Any {
-    /// Returns true if the boxed type is the same as `T`.
+    /// Returns `true` if the boxed type is the same as `T`.
     ///
     /// # Examples
     ///

src/libcore/cmp.rs

@@ -210,7 +210,7 @@ pub enum Ordering {
 }
 
 impl Ordering {
-    /// Reverse the `Ordering`.
+    /// Reverses the `Ordering`.
     ///
     /// * `Less` becomes `Greater`.
     /// * `Greater` becomes `Less`.
@@ -616,7 +616,7 @@ pub trait PartialOrd<Rhs: ?Sized = Self>: PartialEq<Rhs> {
     }
 }
 
-/// Compare and return the minimum of two values.
+/// Compares and returns the minimum of two values.
 ///
 /// Returns the first argument if the comparison determines them to be equal.
 ///
@@ -634,7 +634,7 @@ pub fn min<T: Ord>(v1: T, v2: T) -> T {
     if v1 <= v2 { v1 } else { v2 }
 }
 
-/// Compare and return the maximum of two values.
+/// Compares and returns the maximum of two values.
 ///
 /// Returns the second argument if the comparison determines them to be equal.
 ///

src/libcore/iter_private.rs

@@ -22,7 +22,7 @@
 #[doc(hidden)]
 pub unsafe trait TrustedRandomAccess : ExactSizeIterator {
     unsafe fn get_unchecked(&mut self, i: usize) -> Self::Item;
-    /// Return `true` if getting an iterator element may have
+    /// Returns `true` if getting an iterator element may have
     /// side effects. Remember to take inner iterators into account.
     fn may_have_side_effect() -> bool;
 }

src/libcore/num/bignum.rs

@@ -148,14 +148,14 @@ macro_rules! define_bignum {
                 $name { size: sz, base: base }
             }
 
-            /// Return the internal digits as a slice `[a, b, c, ...]` such that the numeric
+            /// Returns the internal digits as a slice `[a, b, c, ...]` such that the numeric
             /// value is `a + b * 2^W + c * 2^(2W) + ...` where `W` is the number of bits in
             /// the digit type.
             pub fn digits(&self) -> &[$ty] {
                 &self.base[..self.size]
             }
 
-            /// Return the `i`-th bit where bit 0 is the least significant one.
+            /// Returns the `i`-th bit where bit 0 is the least significant one.
             /// In other words, the bit with weight `2^i`.
             pub fn get_bit(&self, i: usize) -> u8 {
                 use mem;
@@ -166,7 +166,7 @@ macro_rules! define_bignum {
                 ((self.base[d] >> b) & 1) as u8
             }
 
-            /// Returns true if the bignum is zero.
+            /// Returns `true` if the bignum is zero.
             pub fn is_zero(&self) -> bool {
                 self.digits().iter().all(|&v| v == 0)
             }

src/libcore/num/mod.rs

@@ -2568,17 +2568,17 @@ pub trait Float: Sized {
                                  implementable outside the standard library")]
     fn one() -> Self;
 
-    /// Returns true if this value is NaN and false otherwise.
+    /// Returns `true` if this value is NaN and false otherwise.
     #[stable(feature = "core", since = "1.6.0")]
     fn is_nan(self) -> bool;
-    /// Returns true if this value is positive infinity or negative infinity and
+    /// Returns `true` if this value is positive infinity or negative infinity and
     /// false otherwise.
     #[stable(feature = "core", since = "1.6.0")]
     fn is_infinite(self) -> bool;
-    /// Returns true if this number is neither infinite nor NaN.
+    /// Returns `true` if this number is neither infinite nor NaN.
     #[stable(feature = "core", since = "1.6.0")]
     fn is_finite(self) -> bool;
-    /// Returns true if this number is neither zero, infinite, denormal, or NaN.
+    /// Returns `true` if this number is neither zero, infinite, denormal, or NaN.
     #[stable(feature = "core", since = "1.6.0")]
     fn is_normal(self) -> bool;
     /// Returns the category that this number falls into.

src/libcore/ptr.rs

@@ -380,7 +380,7 @@ pub unsafe fn write_volatile<T>(dst: *mut T, src: T) {
 
 #[lang = "const_ptr"]
 impl<T: ?Sized> *const T {
-    /// Returns true if the pointer is null.
+    /// Returns `true` if the pointer is null.
     ///
     /// # Examples
     ///
@@ -504,7 +504,7 @@ impl<T: ?Sized> *const T {
 
 #[lang = "mut_ptr"]
 impl<T: ?Sized> *mut T {
-    /// Returns true if the pointer is null.
+    /// Returns `true` if the pointer is null.
     ///
     /// # Examples
     ///

src/libcore/result.rs

@@ -268,7 +268,7 @@ impl<T, E> Result<T, E> {
     // Querying the contained values
     /////////////////////////////////////////////////////////////////////////
 
-    /// Returns true if the result is `Ok`.
+    /// Returns `true` if the result is `Ok`.
     ///
     /// # Examples
     ///
@@ -290,7 +290,7 @@ impl<T, E> Result<T, E> {
         }
     }
 
-    /// Returns true if the result is `Err`.
+    /// Returns `true` if the result is `Err`.
     ///
     /// # Examples
     ///