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)]

src/libcore/num/dec2flt/algorithm.rs

@@ -380,7 +380,7 @@ fn underflow<T: RawFloat>(x: Big, v: Big, rem: Big) -> T {
     // \-----/\-------/ \------------/
     //    q     trunc.    (represented by rem)
     //
-    // Therefore, when the rounded-off bits are != 0.5 ULP, they decide the rounding
+    // Therefore, when the rounded-off bits are not equal to half ULP, they decide the rounding
     // on their own. When they are equal and the remainder is non-zero, the value still
     // needs to be rounded up. Only when the rounded off bits are 1/2 and the remainder
     // is zero, we have a half-to-even situation.

src/libcore/ptr.rs

@@ -185,7 +185,7 @@ pub unsafe fn drop_in_place<T: ?Sized>(to_drop: *mut T) {
 
 // The real `drop_in_place` -- the one that gets called implicitly when variables go
 // out of scope -- should have a safe reference and not a raw pointer as argument
-// type.  When we drop a local variable, we access it with a pointer that behaves
+// type. When we drop a local variable, we access it with a pointer that behaves
 // like a safe reference; transmuting that to a raw pointer does not mean we can
 // actually access it with raw pointers.
 #[lang = "drop_in_place"]
@@ -372,7 +372,7 @@ unsafe fn swap_nonoverlapping_bytes(x: *mut u8, y: *mut u8, len: usize) {
     // #[repr(simd)], even if we don't actually use this struct directly.
     //
     // FIXME repr(simd) broken on emscripten and redox
-    // It's also broken on big-endian powerpc64 and s390x.  #42778
+    // It's also broken on big-endian powerpc64 and s390x. #42778
     #[cfg_attr(not(any(target_os = "emscripten", target_os = "redox",
                        target_endian = "big")),
                repr(simd))]

src/libcore/slice/mod.rs

@@ -451,14 +451,14 @@ impl<T> [T] {
         let ln = self.len();
 
         // For very small types, all the individual reads in the normal
-        // path perform poorly.  We can do better, given efficient unaligned
+        // path perform poorly. We can do better, given efficient unaligned
         // load/store, by loading a larger chunk and reversing a register.
 
         // Ideally LLVM would do this for us, as it knows better than we do
         // whether unaligned reads are efficient (since that changes between
         // different ARM versions, for example) and what the best chunk size
-        // would be.  Unfortunately, as of LLVM 4.0 (2017-05) it only unrolls
-        // the loop, so we need to do this ourselves.  (Hypothesis: reverse
+        // would be. Unfortunately, as of LLVM 4.0 (2017-05) it only unrolls
+        // the loop, so we need to do this ourselves. (Hypothesis: reverse
         // is troublesome because the sides can be aligned differently --
         // will be, when the length is odd -- so there's no way of emitting
         // pre- and postludes to use fully-aligned SIMD in the middle.)
@@ -2106,8 +2106,8 @@ impl<T> [T] {
         #[inline]
         fn gcd(a: usize, b: usize) -> usize {
             // iterative stein’s algorithm
-            // We should still make this `const fn` (and revert to recursive algorithm if we do)
-            // because relying on llvm to consteval all this is… well, it makes me uncomfortable.
+            // We should still make this `const fn` (and revert to recursive algorithm if we do),
+            // because relying on LLVM to const-eval all this does not make me comfortable.
             let (ctz_a, mut ctz_b) = unsafe {
                 if a == 0 { return b; }
                 if b == 0 { return a; }
@@ -2873,7 +2873,7 @@ macro_rules! iterator {
             #[inline(always)]
             unsafe fn post_inc_start(&mut self, offset: isize) -> * $raw_mut T {
                 if mem::size_of::<T>() == 0 {
-                    // This is *reducing* the length.  `ptr` never changes with ZST.
+                    // This is *reducing* the length. `ptr` never changes with ZST.
                     self.end = (self.end as * $raw_mut u8).wrapping_offset(-offset) as * $raw_mut T;
                     self.ptr
                 } else {
@@ -3321,7 +3321,7 @@ impl<T: fmt::Debug, P> fmt::Debug for Split<'_, T, P> where P: FnMut(&T) -> bool
     }
 }
 
-// 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, P> Clone for Split<'_, T, P> where P: Clone + FnMut(&T) -> bool {
     fn clone(&self) -> Self {
@@ -3452,8 +3452,8 @@ impl<'a, T, P> Iterator for SplitMut<'a, T, P> where P: FnMut(&T) -> bool {
         if self.finished {
             (0, Some(0))
         } else {
-            // if the predicate doesn't match anything, we yield one slice
-            // if it matches every element, we yield len+1 empty slices.
+            // If the predicate doesn't match anything, we yield one slice
+            // if it matches every element, we yield `len + 1` empty slices.
             (1, Some(self.v.len() + 1))
         }
     }

src/libcore/tests/pattern.rs

@@ -44,11 +44,11 @@ impl From<Option<(usize, usize)>> for Step {
 
 // ignore-tidy-linelength
 
-// FIXME(Manishearth) these tests focus on single-character searching  (CharSearcher)
-// and on next()/next_match(), not next_reject(). This is because
-// the memchr changes make next_match() for single chars complex, but next_reject()
-// continues to use next() under the hood. We should add more test cases for all
-// of these, as well as tests for StrSearcher and higher level tests for str::find() (etc)
+// FIXME(Manishearth): these tests focus on single-character searching (`CharSearcher`),
+// and on `next()`/`next_match()`, not `next_reject()`. This is because
+// the `memchr` changes make `next_match()` for single chars complex, but `next_reject()`
+// continues to `use next()` under the hood. We should add more test cases for all
+// of these, as well as tests for `StrSearcher` and higher level tests for `str::find()`, etc.
 
 #[test]
 fn test_simple_iteration() {

src/libcore/tests/slice.rs

@@ -810,7 +810,7 @@ mod slice_index {
                 // optional:
                 //
                 // one or more similar inputs for which data[input] succeeds,
-                // and the corresponding output as an array.  This helps validate
+                // and the corresponding output as an array. This helps validate
                 // "critical points" where an input range straddles the boundary
                 // between valid and invalid.
                 // (such as the input `len..len`, which is just barely valid)

src/libproc_macro/bridge/client.rs

@@ -25,7 +25,7 @@ macro_rules! define_handles {
             }
         }
 
-        // FIXME(eddyb) generate the definition of `HandleStore` in `server.rs`.
+        // FIXME(eddyb): generate the definition of `HandleStore` in `server.rs`.
         #[repr(C)]
         #[allow(non_snake_case)]
         pub(super) struct HandleStore<S: server::Types> {
@@ -171,7 +171,7 @@ define_handles! {
     Span,
 }
 
-// FIXME(eddyb) generate these impls by pattern-matching on the
+// FIXME(eddyb): generate these impls by pattern-matching on the
 // names of methods - also could use the presence of `fn drop`
 // to distinguish between 'owned and 'interned, above.
 // Alternatively, special 'modes" could be listed of types in with_api
@@ -201,7 +201,7 @@ impl Clone for Literal {
     }
 }
 
-// FIXME(eddyb) `Literal` should not expose internal `Debug` impls.
+// FIXME(eddyb): `Literal` should not expose internal `Debug` impls.
 impl fmt::Debug for Literal {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.write_str(&self.debug())
@@ -291,7 +291,7 @@ impl BridgeState<'_> {
 impl Bridge<'_> {
     fn enter<R>(self, f: impl FnOnce() -> R) -> R {
         // Hide the default panic output within `proc_macro` expansions.
-        // NB. the server can't do this because it may use a different libstd.
+        // N.B., the server can't do this because it may use a different libstd.
         static HIDE_PANICS_DURING_EXPANSION: Once = Once::new();
         HIDE_PANICS_DURING_EXPANSION.call_once(|| {
             let prev = panic::take_hook();