libs: comments

Author: Alexander Regueiro

src/liballoc/alloc.rs

@@ -1,4 +1,4 @@
-//! Memory allocation APIs
+//! Memory allocation APIs.
 
 #![stable(feature = "alloc_module", since = "1.28.0")]
 
@@ -38,7 +38,7 @@ extern "Rust" {
 #[derive(Copy, Clone, Default, Debug)]
 pub struct Global;
 
-/// Allocate memory with the global allocator.
+/// Allocates memory with the global allocator.
 ///
 /// This function forwards calls to the [`GlobalAlloc::alloc`] method
 /// of the allocator registered with the `#[global_allocator]` attribute
@@ -72,7 +72,7 @@ pub unsafe fn alloc(layout: Layout) -> *mut u8 {
     __rust_alloc(layout.size(), layout.align())
 }
 
-/// Deallocate memory with the global allocator.
+/// Deallocates memory with the global allocator.
 ///
 /// This function forwards calls to the [`GlobalAlloc::dealloc`] method
 /// of the allocator registered with the `#[global_allocator]` attribute
@@ -90,7 +90,7 @@ pub unsafe fn dealloc(ptr: *mut u8, layout: Layout) {
     __rust_dealloc(ptr, layout.size(), layout.align())
 }
 
-/// Reallocate memory with the global allocator.
+/// Reallocates memory with the global allocator.
 ///
 /// This function forwards calls to the [`GlobalAlloc::realloc`] method
 /// of the allocator registered with the `#[global_allocator]` attribute
@@ -108,7 +108,7 @@ pub unsafe fn realloc(ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8
     __rust_realloc(ptr, layout.size(), layout.align(), new_size)
 }
 
-/// Allocate zero-initialized memory with the global allocator.
+/// Allocates zero-initialized memory with the global allocator.
 ///
 /// This function forwards calls to the [`GlobalAlloc::alloc_zeroed`] method
 /// of the allocator registered with the `#[global_allocator]` attribute
@@ -170,6 +170,7 @@ unsafe impl Alloc for Global {
 }
 
 /// The allocator for unique pointers.
+//
 // This function must not unwind. If it does, MIR codegen will fail.
 #[cfg(not(test))]
 #[lang = "exchange_malloc"]
@@ -194,14 +195,15 @@ pub(crate) unsafe fn box_free<T: ?Sized>(ptr: Unique<T>) {
     let ptr = ptr.as_ptr();
     let size = size_of_val(&*ptr);
     let align = min_align_of_val(&*ptr);
-    // We do not allocate for Box<T> when T is ZST, so deallocation is also not necessary.
+    // We do not allocate for `Box<T>` when `T` is zero-sized, so deallocation is also not
+    // necessary.
     if size != 0 {
         let layout = Layout::from_size_align_unchecked(size, align);
         dealloc(ptr as *mut u8, layout);
     }
 }
 
-/// Abort on memory allocation error or failure.
+/// Aborts on memory allocation error or failure.
 ///
 /// Callers of memory allocation APIs wishing to abort computation
 /// in response to an allocation error are encouraged to call this function,

src/liballoc/boxed.rs

@@ -275,7 +275,7 @@ impl<T: ?Sized> Box<T> {
 #[stable(feature = "rust1", since = "1.0.0")]
 unsafe impl<#[may_dangle] T: ?Sized> Drop for Box<T> {
     fn drop(&mut self) {
-        // FIXME: Do nothing, drop is currently performed by compiler.
+        // FIXME: do nothing; drop is currently performed by compiler.
     }
 }
 

src/liballoc/collections/binary_heap.rs

@@ -945,7 +945,7 @@ impl<T: fmt::Debug> fmt::Debug for Iter<'_, T> {
     }
 }
 
-// FIXME(#26925) Remove in favor of `#[derive(Clone)]`
+// FIXME(#26925): Remove in favor of `#[derive(Clone)]`.
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<'a, T> Clone for Iter<'a, T> {
     fn clone(&self) -> Iter<'a, T> {

src/liballoc/collections/btree/map.rs

@@ -887,7 +887,7 @@ impl<K: Ord, V> BTreeMap<K, V> {
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn entry(&mut self, key: K) -> Entry<'_, K, V> {
-        // FIXME(@porglezomp) Avoid allocating if we don't insert
+        // FIXME(porglezomp): avoid allocating if we don't insert.
         self.ensure_root_is_owned();
         match search::search_tree(self.root.as_mut(), &key) {
             Found(handle) => {

src/liballoc/collections/btree/node.rs

@@ -1,4 +1,4 @@
-// This is an attempt at an implementation following the ideal
+// This is an attempt at an implementation of the following ideal:
 //
 // ```
 // struct BTreeMap<K, V> {
@@ -250,7 +250,7 @@ impl<K, V> Root<K, V> {
         NodeRef {
             height: self.height,
             node: self.node.as_ptr(),
-            root: ptr::null_mut(), // FIXME: Is there anything better to do here?
+            root: ptr::null_mut(), // FIXME: is there anything better to do here?
             _marker: PhantomData,
         }
     }
@@ -305,7 +305,7 @@ impl<K, V> Root<K, V> {
     }
 }
 
-// N.B. `NodeRef` is always covariant in `K` and `V`, even when the `BorrowType`
+// N.B., `NodeRef` is always covariant in `K` and `V`, even when the `BorrowType`
 // is `Mut`. This is technically wrong, but cannot result in any unsafety due to
 // internal use of `NodeRef` because we stay completely generic over `K` and `V`.
 // However, whenever a public type wraps `NodeRef`, make sure that it has the
@@ -322,8 +322,8 @@ impl<K, V> Root<K, V> {
 ///   `Leaf`, the `NodeRef` points to a leaf node, when this is `Internal` the
 ///   `NodeRef` points to an internal node, and when this is `LeafOrInternal` the
 ///   `NodeRef` could be pointing to either type of node.
-///   Note that in case of a leaf node, this might still be the shared root!  Only turn
-///   this into a `LeafNode` reference if you know it is not a root!  Shared references
+///   Note that in case of a leaf node, this might still be the shared root! Only turn
+///   this into a `LeafNode` reference if you know it is not a root! Shared references
 ///   must be dereferencable *for the entire size of their pointee*, so `&InternalNode`
 ///   pointing to the shared root is UB.
 ///   Turning this into a `NodeHeader` is always safe.
@@ -562,7 +562,7 @@ impl<'a, K, V, Type> NodeRef<marker::Mut<'a>, K, V, Type> {
 
     /// Returns a raw ptr to avoid asserting exclusive access to the entire node.
     fn as_leaf_mut(&mut self) -> *mut LeafNode<K, V> {
-        // We are mutable, so we cannot be the root, so accessing this as a leaf is okay.
+        // We are mutable, so we cannot be the root, so accessing this as a leaf is ok.
         self.node.as_ptr()
     }
 
@@ -585,7 +585,7 @@ impl<'a, K: 'a, V: 'a, Type> NodeRef<marker::Immut<'a>, K, V, Type> {
         // We can sometimes do this even for the shared root, as the slice will be
         // empty. We cannot *always* do this because if the type is too highly
         // aligned, the offset of `keys` in a "full node" might be outside the bounds
-        // of the header!  So we do an alignment check first, that will be
+        // of the header! So we do an alignment check first, that will be
         // evaluated at compile-time, and only do any run-time check in the rare case
         // that the alignment is very big.
         if mem::align_of::<K>() > mem::align_of::<LeafNode<(), ()>>() && self.is_shared_root() {
@@ -602,10 +602,10 @@ impl<'a, K: 'a, V: 'a, Type> NodeRef<marker::Immut<'a>, K, V, Type> {
             // and hence just adds a size-0-align-1 field, not affecting layout).
             // We know that we can transmute `NodeHeader<K, V, ()>` to `NodeHeader<K, V, K>`
             // because we did the alignment check above, and hence `NodeHeader<K, V, K>`
-            // is not bigger than `NodeHeader<K, V, ()>`!  Then we can use `NodeHeader<K, V, K>`
+            // is not bigger than `NodeHeader<K, V, ()>`! Then we can use `NodeHeader<K, V, K>`
             // to compute the pointer where the keys start.
             // This entire hack will become unnecessary once
-            // <https://github.com/rust-lang/rfcs/pull/2582> lands, then we can just take a raw
+            // RFC #2582 lands, then we can just take a raw
             // pointer to the `keys` field of `*const InternalNode<K, V>`.
 
             // This is a non-debug-assert because it can be completely compile-time evaluated.
@@ -620,7 +620,7 @@ impl<'a, K: 'a, V: 'a, Type> NodeRef<marker::Immut<'a>, K, V, Type> {
 
     fn into_val_slice(self) -> &'a [V] {
         debug_assert!(!self.is_shared_root());
-        // We cannot be the root, so `as_leaf` is okay
+        // We cannot be the root, so `as_leaf` is ok
         unsafe {
             slice::from_raw_parts(
                 MaybeUninit::first_ptr(&self.as_leaf().vals),

src/liballoc/collections/linked_list.rs

@@ -69,7 +69,7 @@ impl<T: fmt::Debug> fmt::Debug for Iter<'_, T> {
     }
 }
 
-// FIXME(#26925) Remove in favor of `#[derive(Clone)]`
+// FIXME(#26925): Remove in favor of `#[derive(Clone)]`.
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T> Clone for Iter<'_, T> {
     fn clone(&self) -> Self {
@@ -1383,7 +1383,7 @@ mod tests {
         // This caused the RHS's dtor to walk up into the LHS at drop and delete all of
         // its nodes.
         //
-        // https://github.com/rust-lang/rust/issues/26021
+        // Issue #26021.
         let mut v1 = LinkedList::new();
         v1.push_front(1);
         v1.push_front(1);

src/liballoc/collections/vec_deque.rs

@@ -151,7 +151,7 @@ impl<T> VecDeque<T> {
         wrap_index(idx.wrapping_sub(subtrahend), self.cap())
     }
 
-    /// Copies a contiguous block of memory len long from src to dst
+    /// Copies a contiguous block of memory len long from `src` to `dst`.
     #[inline]
     unsafe fn copy(&self, dst: usize, src: usize, len: usize) {
         debug_assert!(dst + len <= self.cap(),
@@ -171,7 +171,7 @@ impl<T> VecDeque<T> {
                   len);
     }
 
-    /// Copies a contiguous block of memory len long from src to dst
+    /// Copies a contiguous block of memory len long from `src` to `dst`.
     #[inline]
     unsafe fn copy_nonoverlapping(&self, dst: usize, src: usize, len: usize) {
         debug_assert!(dst + len <= self.cap(),
@@ -191,9 +191,9 @@ impl<T> VecDeque<T> {
                                  len);
     }
 
-    /// Copies a potentially wrapping block of memory len long from src to dest.
-    /// (abs(dst - src) + len) must be no larger than cap() (There must be at
-    /// most one continuous overlapping region between src and dest).
+    /// Copies a potentially wrapping block of memory len long from `src` to `dest`.
+    /// `abs(dst - src) + len` must be no larger than `cap()`. (There must be at
+    /// most one continuous overlapping region between `src` and `dest`).
     unsafe fn wrap_copy(&self, dst: usize, src: usize, len: usize) {
         #[allow(dead_code)]
         fn diff(a: usize, b: usize) -> usize {
@@ -219,7 +219,7 @@ impl<T> VecDeque<T> {
 
         match (dst_after_src, src_wraps, dst_wraps) {
             (_, false, false) => {
-                // src doesn't wrap, dst doesn't wrap
+                // `src` doesn't wrap, `dst` doesn't wrap.
                 //
                 //        S . . .
                 // 1 [_ _ A A B B C C _]
@@ -229,7 +229,7 @@ impl<T> VecDeque<T> {
                 self.copy(dst, src, len);
             }
             (false, false, true) => {
-                // dst before src, src doesn't wrap, dst wraps
+                // `dst` before `src`, `src` doesn't wrap, `dst` wraps.
                 //
                 //    S . . .
                 // 1 [A A B B _ _ _ C C]
@@ -241,7 +241,7 @@ impl<T> VecDeque<T> {
                 self.copy(0, src + dst_pre_wrap_len, len - dst_pre_wrap_len);
             }
             (true, false, true) => {
-                // src before dst, src doesn't wrap, dst wraps
+                // `src` before `dst`, `src` doesn't wrap, `dst` wraps.
                 //
                 //              S . . .
                 // 1 [C C _ _ _ A A B B]
@@ -253,7 +253,7 @@ impl<T> VecDeque<T> {
                 self.copy(dst, src, dst_pre_wrap_len);
             }
             (false, true, false) => {
-                // dst before src, src wraps, dst doesn't wrap
+                // `dst` before `src`, `src` wraps, `dst` doesn't wrap.
                 //
                 //    . .           S .
                 // 1 [C C _ _ _ A A B B]
@@ -265,7 +265,7 @@ impl<T> VecDeque<T> {
                 self.copy(dst + src_pre_wrap_len, 0, len - src_pre_wrap_len);
             }
             (true, true, false) => {
-                // src before dst, src wraps, dst doesn't wrap
+                // `src` before `dst`, `src` wraps, `dst` doesn't wrap.
                 //
                 //    . .           S .
                 // 1 [A A B B _ _ _ C C]
@@ -277,7 +277,7 @@ impl<T> VecDeque<T> {
                 self.copy(dst, src, src_pre_wrap_len);
             }
             (false, true, true) => {
-                // dst before src, src wraps, dst wraps
+                // `dst` before `src`, `src` wraps, `dst` wraps.
                 //
                 //    . . .         S .
                 // 1 [A B C D _ E F G H]
@@ -293,7 +293,7 @@ impl<T> VecDeque<T> {
                 self.copy(0, delta, len - dst_pre_wrap_len);
             }
             (true, true, true) => {
-                // src before dst, src wraps, dst wraps
+                // `src` before `dst`, `src` wraps, `dst` wraps.
                 //
                 //    . .         S . .
                 // 1 [A B C D _ E F G H]
@@ -312,7 +312,7 @@ impl<T> VecDeque<T> {
     }
 
     /// Frobs the head and tail sections around to handle the fact that we
-    /// just reallocated. Unsafe because it trusts old_cap.
+    /// just reallocated. Unsafe because it trusts `old_cap`.
     #[inline]
     unsafe fn handle_cap_increase(&mut self, old_cap: usize) {
         let new_cap = self.cap();
@@ -333,7 +333,7 @@ impl<T> VecDeque<T> {
 
         if self.tail <= self.head {
             // A
-            // Nop
+            // No-op.
         } else if self.head < old_cap - self.tail {
             // B
             self.copy_nonoverlapping(old_cap, 0, self.head);
@@ -2130,7 +2130,7 @@ impl<T: fmt::Debug> fmt::Debug for Iter<'_, T> {
     }
 }
 
-// FIXME(#26925) Remove in favor of `#[derive(Clone)]`
+// FIXME(#26925): Remove in favor of `#[derive(Clone)]`.
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<'a, T> Clone for Iter<'a, T> {
     fn clone(&self) -> Iter<'a, T> {
@@ -3125,5 +3125,4 @@ mod tests {
             assert_eq!(*a, 2);
         }
     }
-
 }

src/liballoc/fmt.rs

@@ -205,7 +205,7 @@
 //! These two formatting traits have distinct purposes:
 //!
 //! - [`fmt::Display`][`Display`] implementations assert that the type can be faithfully
-//!   represented as a UTF-8 string at all times. It is **not** expected that
+//!   represented as a UTF-8 string at all times. It is *not* expected that
 //!   all types implement the [`Display`] trait.
 //! - [`fmt::Debug`][`Debug`] implementations should be implemented for **all** public types.
 //!   Output will typically represent the internal state as faithfully as possible.

src/liballoc/lib.rs

@@ -135,7 +135,7 @@ pub mod alloc;
 // Primitive types using the heaps above
 
 // Need to conditionally define the mod from `boxed.rs` to avoid
-// duplicating the lang-items when building in test cfg; but also need
+// duplicating the lang-items when building in test cfg, but also need
 // to allow code to have `use boxed::Box;` declarations.
 #[cfg(not(test))]
 pub mod boxed;

src/liballoc/macros.rs

@@ -46,7 +46,7 @@ macro_rules! vec {
     ($($x:expr,)*) => (vec![$($x),*])
 }
 
-// HACK(japaric): with cfg(test) the inherent `[T]::into_vec` method, which is
+// HACK(japaric): with `cfg(test)`, the inherent `[T]::into_vec` method, which is
 // required for this macro definition, is not available. Instead use the
 // `slice::into_vec`  function which is only available with cfg(test)
 // NB see the slice::hack module in slice.rs for more information