libs: doc comments

Author: Alexander Regueiro

src/liballoc/borrow.rs

@@ -137,11 +137,11 @@ impl<T> ToOwned for T
 /// ```
 /// use std::borrow::{Cow, ToOwned};
 ///
-/// struct Items<'a, X: 'a> where [X]: ToOwned<Owned=Vec<X>> {
+/// struct Items<'a, X: 'a> where [X]: ToOwned<Owned = Vec<X>> {
 ///     values: Cow<'a, [X]>,
 /// }
 ///
-/// impl<'a, X: Clone + 'a> Items<'a, X> where [X]: ToOwned<Owned=Vec<X>> {
+/// impl<'a, X: Clone + 'a> Items<'a, X> where [X]: ToOwned<Owned = Vec<X>> {
 ///     fn new(v: Cow<'a, [X]>) -> Self {
 ///         Items { values: v }
 ///     }

src/liballoc/collections/binary_heap.rs

@@ -863,7 +863,7 @@ struct Hole<'a, T: 'a> {
 }
 
 impl<'a, T> Hole<'a, T> {
-    /// Create a new Hole at index `pos`.
+    /// Create a new `Hole` at index `pos`.
     ///
     /// Unsafe because pos must be within the data slice.
     #[inline]

src/liballoc/collections/btree/map.rs

@@ -2368,7 +2368,7 @@ impl<'a, K: Ord, V> OccupiedEntry<'a, K, V> {
 
     /// Gets a mutable reference to the value in the entry.
     ///
-    /// If you need a reference to the `OccupiedEntry` which may outlive the
+    /// If you need a reference to the `OccupiedEntry` that may outlive the
     /// destruction of the `Entry` value, see [`into_mut`].
     ///
     /// [`into_mut`]: #method.into_mut

src/liballoc/collections/btree/node.rs

@@ -1295,7 +1295,7 @@ impl<'a, K, V> Handle<NodeRef<marker::Mut<'a>, K, V, marker::Internal>, marker::
         }
     }
 
-    /// Returns whether it is valid to call `.merge()`, i.e., whether there is enough room in
+    /// Returns `true` if it is valid to call `.merge()`, i.e., whether there is enough room in
     /// a node to hold the combination of the nodes to the left and right of this handle along
     /// with the key/value pair at this handle.
     pub fn can_merge(&self) -> bool {
@@ -1573,7 +1573,7 @@ unsafe fn move_edges<K, V>(
 impl<BorrowType, K, V, HandleType>
         Handle<NodeRef<BorrowType, K, V, marker::LeafOrInternal>, HandleType> {
 
-    /// Check whether the underlying node is an `Internal` node or a `Leaf` node.
+    /// Checks whether the underlying node is an `Internal` node or a `Leaf` node.
     pub fn force(self) -> ForceResult<
         Handle<NodeRef<BorrowType, K, V, marker::Leaf>, HandleType>,
         Handle<NodeRef<BorrowType, K, V, marker::Internal>, HandleType>

src/liballoc/collections/btree/set.rs

@@ -556,7 +556,7 @@ impl<T: Ord> BTreeSet<T> {
         Recover::replace(&mut self.map, value)
     }
 
-    /// Removes a value from the set. Returns `true` if the value was
+    /// Removes a value from the set. Returns whether the value was
     /// present in the set.
     ///
     /// The value may be any borrowed form of the set's value type,
@@ -988,7 +988,7 @@ impl<'a, T> DoubleEndedIterator for Range<'a, T> {
 #[stable(feature = "fused", since = "1.26.0")]
 impl<T> FusedIterator for Range<'_, T> {}
 
-/// Compare `x` and `y`, but return `short` if x is None and `long` if y is None
+/// Compares `x` and `y`, but return `short` if x is None and `long` if y is None
 fn cmp_opt<T: Ord>(x: Option<&T>, y: Option<&T>, short: Ordering, long: Ordering) -> Ordering {
     match (x, y) {
         (None, _) => short,

src/liballoc/collections/vec_deque.rs

@@ -124,7 +124,7 @@ impl<T> VecDeque<T> {
         ptr::write(self.ptr().add(off), value);
     }
 
-    /// Returns `true` if and only if the buffer is at full capacity.
+    /// Returns `true` if the buffer is at full capacity.
     #[inline]
     fn is_full(&self) -> bool {
         self.cap() - self.len() == 1
@@ -560,7 +560,7 @@ impl<T> VecDeque<T> {
     /// 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
+    /// requests. Therefore, capacity can not be relied upon to be precisely
     /// minimal. Prefer `reserve` if future insertions are expected.
     ///
     /// # Errors
@@ -924,15 +924,15 @@ impl<T> VecDeque<T> {
         self.tail == self.head
     }
 
-    /// Create a draining iterator that removes the specified range in the
+    /// Creates a draining iterator that removes the specified range in the
     /// `VecDeque` and yields the removed items.
     ///
     /// Note 1: The element range is removed even if the iterator is not
     /// 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).
+    /// (e.g., due to `mem::forget`).
     ///
     /// # Panics
     ///

src/liballoc/macros.rs

@@ -67,7 +67,7 @@ macro_rules! vec {
 ///
 /// Additional parameters passed to `format!` replace the `{}`s within the
 /// formatting string in the order given unless named or positional parameters
-/// are used, see [`std::fmt`][fmt] for more information.
+/// are used; see [`std::fmt`][fmt] for more information.
 ///
 /// A common use for `format!` is concatenation and interpolation of strings.
 /// The same convention is used with [`print!`] and [`write!`] macros,

src/liballoc/raw_vec.rs

@@ -335,7 +335,7 @@ impl<T, A: Alloc> RawVec<T, A> {
     /// enough to want to do that it's easiest to just have a dedicated method. Slightly
     /// more efficient logic can be provided for this than the general case.
     ///
-    /// Returns true if the reallocation attempt has succeeded, or false otherwise.
+    /// Returns `true` if the reallocation attempt has succeeded.
     ///
     /// # Panics
     ///
@@ -504,7 +504,7 @@ impl<T, A: Alloc> RawVec<T, A> {
     /// the requested space. This is not really unsafe, but the unsafe
     /// code *you* write that relies on the behavior of this function may break.
     ///
-    /// Returns true if the reallocation attempt has succeeded, or false otherwise.
+    /// Returns `true` if the reallocation attempt has succeeded.
     ///
     /// # Panics
     ///

src/liballoc/rc.rs

@@ -512,7 +512,7 @@ impl<T: ?Sized> Rc<T> {
         this.strong()
     }
 
-    /// Returns true if there are no other `Rc` or [`Weak`][weak] pointers to
+    /// Returns `true` if there are no other `Rc` or [`Weak`][weak] pointers to
     /// this inner value.
     ///
     /// [weak]: struct.Weak.html
@@ -561,7 +561,7 @@ impl<T: ?Sized> Rc<T> {
 
     #[inline]
     #[stable(feature = "ptr_eq", since = "1.17.0")]
-    /// Returns true if the two `Rc`s point to the same value (not
+    /// Returns `true` if the two `Rc`s point to the same value (not
     /// just values that compare as equal).
     ///
     /// # Examples
@@ -1334,8 +1334,8 @@ impl<T: ?Sized> Weak<T> {
         })
     }
 
-    /// Return `None` when the pointer is dangling and there is no allocated `RcBox`,
-    /// i.e., this `Weak` was created by `Weak::new`
+    /// Returns `None` when the pointer is dangling and there is no allocated `RcBox`
+    /// (i.e., when this `Weak` was created by `Weak::new`).
     #[inline]
     fn inner(&self) -> Option<&RcBox<T>> {
         if is_dangling(self.ptr) {
@@ -1345,7 +1345,7 @@ impl<T: ?Sized> Weak<T> {
         }
     }
 
-    /// Returns true if the two `Weak`s point to the same value (not just values
+    /// Returns `true` if the two `Weak`s point to the same value (not just values
     /// that compare as equal).
     ///
     /// # Notes

src/liballoc/slice.rs

@@ -205,10 +205,10 @@ impl<T> [T] {
     ///
     /// The comparator function must define a total ordering for the elements in the slice. If
     /// the ordering is not total, the order of the elements is unspecified. An order is a
-    /// total order if it is (for all a, b and c):
+    /// total order if it is (for all `a`, `b` and `c`):
     ///
-    /// * total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
-    /// * transitive, a < b and b < c implies a < c. The same must hold for both == and >.
+    /// * total and antisymmetric: exactly one of `a < b`, `a == b` or `a > b` is true, and
+    /// * transitive, `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`.
     ///
     /// For example, while [`f64`] doesn't implement [`Ord`] because `NaN != NaN`, we can use
     /// `partial_cmp` as our sort function when we know the slice doesn't contain a `NaN`.