tests: comments

Author: Alexander Regueiro

src/liballoc/alloc.rs

@@ -11,7 +11,7 @@ use core::usize;
 pub use core::alloc::*;
 
 extern "Rust" {
-    // These are the magic symbols to call the global allocator.  rustc generates
+    // These are the magic symbols to call the global allocator. rustc generates
     // them from the `#[global_allocator]` attribute if there is one, or uses the
     // default implementations in libstd (`__rdl_alloc` etc in `src/libstd/alloc.rs`)
     // otherwise.

src/liballoc/collections/btree/node.rs

@@ -549,7 +549,7 @@ impl<'a, K, V, Type> NodeRef<marker::Mut<'a>, K, V, Type> {
     /// `into_root_mut`) mess with the root of the tree, the result of `reborrow_mut`
     /// can easily be used to make the original mutable pointer dangling, or, in the case
     /// of a reborrowed handle, out of bounds.
-    // FIXME(@gereeter) consider adding yet another type parameter to `NodeRef` that restricts
+    // FIXME(gereeter): consider adding yet another type parameter to `NodeRef` that restricts
     // the use of `ascend` and `into_root_mut` on reborrowed pointers, preventing this unsafety.
     unsafe fn reborrow_mut(&mut self) -> NodeRef<marker::Mut<'_>, K, V, Type> {
         NodeRef {
@@ -578,12 +578,12 @@ impl<'a, K, V, Type> NodeRef<marker::Mut<'a>, K, V, Type> {
 impl<'a, K: 'a, V: 'a, Type> NodeRef<marker::Immut<'a>, K, V, Type> {
     fn into_key_slice(self) -> &'a [K] {
         // We have to be careful here because we might be pointing to the shared root.
-        // In that case, we must not create an `&LeafNode`.  We could just return
+        // In that case, we must not create an `&LeafNode`. We could just return
         // an empty slice whenever the length is 0 (this includes the shared root),
         // but we want to avoid that run-time check.
         // Instead, we create a slice pointing into the node whenever possible.
         // 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
+        // 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
         // evaluated at compile-time, and only do any run-time check in the rare case
@@ -594,9 +594,9 @@ impl<'a, K: 'a, V: 'a, Type> NodeRef<marker::Immut<'a>, K, V, Type> {
             // Thanks to the alignment check above, we know that `keys` will be
             // in-bounds of some allocation even if this is the shared root!
             // (We might be one-past-the-end, but that is allowed by LLVM.)
-            // Getting the pointer is tricky though.  `NodeHeader` does not have a `keys`
+            // Getting the pointer is tricky though. `NodeHeader` does not have a `keys`
             // field because we want its size to not depend on the alignment of `K`
-            // (needed becuase `as_header` should be safe).  We cannot call `as_leaf`
+            // (needed becuase `as_header` should be safe). We cannot call `as_leaf`
             // because we might be the shared root.
             // For this reason, `NodeHeader` has this `K2` parameter (that's usually `()`
             // and hence just adds a size-0-align-1 field, not affecting layout).
@@ -950,7 +950,7 @@ impl<'a, K, V, NodeType, HandleType>
     /// `into_root_mut`) mess with the root of the tree, the result of `reborrow_mut`
     /// can easily be used to make the original mutable pointer dangling, or, in the case
     /// of a reborrowed handle, out of bounds.
-    // FIXME(@gereeter) consider adding yet another type parameter to `NodeRef` that restricts
+    // FIXME(gereeter): consider adding yet another type parameter to `NodeRef` that restricts
     // the use of `ascend` and `into_root_mut` on reborrowed pointers, preventing this unsafety.
     pub unsafe fn reborrow_mut(&mut self)
             -> Handle<NodeRef<marker::Mut<'_>, K, V, NodeType>, HandleType> {

src/liballoc/collections/vec_deque.rs

@@ -1014,7 +1014,7 @@ impl<T> VecDeque<T> {
                 tail: drain_tail,
                 head: drain_head,
                 // Crucially, we only create shared references from `self` here and read from
-                // it.  We do not write to `self` nor reborrow to a mutable reference.
+                // it. We do not write to `self` nor reborrow to a mutable reference.
                 // Hence the raw pointer we created above, for `deque`, remains valid.
                 ring: unsafe { self.buffer_as_slice() },
             },

src/liballoc/raw_vec.rs

@@ -651,7 +651,7 @@ impl<T, A: Alloc> RawVec<T, A> {
                 return Ok(());
             }
 
-            // Nothing we can really do about these checks :(
+            // Nothing we can really do about these checks.
             let new_cap = match strategy {
                 Exact => used_cap.checked_add(needed_extra_cap).ok_or(CapacityOverflow)?,
                 Amortized => self.amortized_new_size(used_cap, needed_extra_cap)?,
@@ -794,7 +794,7 @@ mod tests {
     fn reserve_does_not_overallocate() {
         {
             let mut v: RawVec<u32> = RawVec::new();
-            // First `reserve` allocates like `reserve_exact`
+            // First `reserve` allocates like `reserve_exact`.
             v.reserve(0, 9);
             assert_eq!(9, v.cap());
         }
@@ -817,7 +817,7 @@ mod tests {
             // 3 is less than half of 12, so `reserve` must grow
             // exponentially. At the time of writing this test grow
             // factor is 2, so new capacity is 24, however, grow factor
-            // of 1.5 is OK too. Hence `>= 18` in assert.
+            // of 1.5 is ok too. Hence `>= 18` in assert.
             assert!(v.cap() >= 12 + 12 / 2);
         }
     }

src/liballoc/rc.rs

@@ -1220,7 +1220,7 @@ pub struct Weak<T: ?Sized> {
     // This is a `NonNull` to allow optimizing the size of this type in enums,
     // but it is not necessarily a valid pointer.
     // `Weak::new` sets this to `usize::MAX` so that it doesn’t need
-    // to allocate space on the heap.  That's not a value a real pointer
+    // to allocate space on the heap. That's not a value a real pointer
     // will ever have because RcBox has alignment at least 2.
     ptr: NonNull<RcBox<T>>,
 }

src/liballoc/sync.rs

@@ -234,7 +234,7 @@ pub struct Weak<T: ?Sized> {
     // This is a `NonNull` to allow optimizing the size of this type in enums,
     // but it is not necessarily a valid pointer.
     // `Weak::new` sets this to `usize::MAX` so that it doesn’t need
-    // to allocate space on the heap.  That's not a value a real pointer
+    // to allocate space on the heap. That's not a value a real pointer
     // will ever have because RcBox has alignment at least 2.
     ptr: NonNull<ArcInner<T>>,
 }
@@ -749,7 +749,7 @@ impl<T: ?Sized> Clone for Arc<T> {
         // [1]: (www.boost.org/doc/libs/1_55_0/doc/html/atomic/usage_examples.html)
         let old_size = self.inner().strong.fetch_add(1, Relaxed);
 
-        // However we need to guard against massive refcounts in case someone
+        // However we need to guard against massive ref counts in case someone
         // is `mem::forget`ing Arcs. If we don't do this the count can overflow
         // and users will use-after free. We racily saturate to `isize::MAX` on
         // the assumption that there aren't ~2 billion threads incrementing
@@ -920,7 +920,7 @@ impl<T: ?Sized> Arc<T> {
         //
         // The acquire label here ensures a happens-before relationship with any
         // writes to `strong` (in particular in `Weak::upgrade`) prior to decrements
-        // of the `weak` count (via `Weak::drop`, which uses release).  If the upgraded
+        // of the `weak` count (via `Weak::drop`, which uses release). If the upgraded
         // weak ref was never dropped, the CAS here will fail so we do not care to synchronize.
         if self.inner().weak.compare_exchange(1, usize::MAX, Acquire, Relaxed).is_ok() {
             // This needs to be an `Acquire` to synchronize with the decrement of the `strong`
@@ -978,7 +978,7 @@ unsafe impl<#[may_dangle] T: ?Sized> Drop for Arc<T> {
         }
 
         // This fence is needed to prevent reordering of use of the data and
-        // deletion of the data.  Because it is marked `Release`, the decreasing
+        // deletion of the data. Because it is marked `Release`, the decreasing
         // of the reference count synchronizes with this `Acquire` fence. This
         // means that use of the data happens before decreasing the reference
         // count, which happens before this fence, which happens before the
@@ -1270,13 +1270,13 @@ impl<T: ?Sized> Clone for Weak<T> {
         } else {
             return Weak { ptr: self.ptr };
         };
-        // See comments in Arc::clone() for why this is relaxed.  This can use a
-        // fetch_add (ignoring the lock) because the weak count is only locked
+        // See comments in `Arc::clone()` for why this is relaxed. This can use a
+        // `fetch_add` (ignoring the lock) because the weak count is only locked
         // where are *no other* weak pointers in existence. (So we can't be
         // running this code in that case).
         let old_size = inner.weak.fetch_add(1, Relaxed);
 
-        // See comments in Arc::clone() for why we do this (for mem::forget).
+        // See comments in `Arc::clone()` for why we do this (for `mem::forget`).
         if old_size > MAX_REFCOUNT {
             unsafe {
                 abort();

src/liballoc/tests/lib.rs

@@ -35,8 +35,8 @@ fn hash<T: Hash>(t: &T) -> u64 {
     s.finish()
 }
 
-// FIXME: Instantiated functions with i128 in the signature is not supported in Emscripten.
-// See https://github.com/kripken/emscripten-fastcomp/issues/169
+// FIXME: instantiated functions with `i128` in the signature is not supported in Emscripten.
+// See <https://github.com/kripken/emscripten-fastcomp/issues/169>.
 #[cfg(not(target_os = "emscripten"))]
 #[test]
 fn test_boxed_hasher() {

src/libcore/cell.rs

@@ -1310,8 +1310,8 @@ impl<'b> BorrowRefMut<'b> {
     fn new(borrow: &'b Cell<BorrowFlag>) -> Option<BorrowRefMut<'b>> {
         // NOTE: Unlike BorrowRefMut::clone, new is called to create the initial
         // mutable reference, and so there must currently be no existing
-        // references. Thus, while clone increments the mutable refcount, here
-        // we explicitly only allow going from UNUSED to UNUSED - 1.
+        // references. Thus, while clone increments the mutable ref count, here
+        // we explicitly only allow going from `UNUSED` to `UNUSED - 1`.
         match borrow.get() {
             UNUSED => {
                 borrow.set(UNUSED - 1);

src/libcore/fmt/float.rs

@@ -13,7 +13,7 @@ fn float_to_decimal_common_exact<T>(fmt: &mut Formatter, num: &T,
         let mut buf = MaybeUninit::<[u8; 1024]>::uninitialized(); // enough for f32 and f64
         let mut parts = MaybeUninit::<[flt2dec::Part; 4]>::uninitialized();
         // FIXME(#53491): Technically, this is calling `get_mut` on an uninitialized
-        // `MaybeUninit` (here and elsewhere in this file).  Revisit this once
+        // `MaybeUninit` (here and elsewhere in this file). Revisit this once
         // we decided whether that is valid or not.
         let formatted = flt2dec::to_exact_fixed_str(flt2dec::strategy::grisu::format_exact,
                                                     *num, sign, precision,

src/libcore/mem.rs

@@ -1176,7 +1176,7 @@ impl<T> MaybeUninit<T> {
     /// It is up to the caller to guarantee that the `MaybeUninit` really is in an initialized
     /// state, otherwise this will immediately cause undefined behavior.
     // FIXME(#53491): We currently rely on the above being incorrect, i.e., we have references
-    // to uninitialized data (e.g., in `libcore/fmt/float.rs`).  We should make
+    // to uninitialized data (e.g., in `libcore/fmt/float.rs`). We should make
     // a final decision about the rules before stabilization.
     #[unstable(feature = "maybe_uninit", issue = "53491")]
     #[inline(always)]