Various minor/cosmetic improvements to code

src/bootstrap/builder.rs

@@ -793,7 +793,7 @@ impl<'a> Builder<'a> {
         }
 
         // Set a flag for `check` so that certain build scripts can do less work
-        // (e.g. not building/requiring LLVM).
+        // (e.g., not building/requiring LLVM).
         if cmd == "check" {
             cargo.env("RUST_CHECK", "1");
         }
@@ -923,12 +923,12 @@ impl<'a> Builder<'a> {
             cargo.env("RUSTC_FORCE_UNSTABLE", "1");
 
             // Currently the compiler depends on crates from crates.io, and
-            // then other crates can depend on the compiler (e.g. proc-macro
+            // then other crates can depend on the compiler (e.g., proc-macro
             // crates). Let's say, for example that rustc itself depends on the
             // bitflags crate. If an external crate then depends on the
             // bitflags crate as well, we need to make sure they don't
             // conflict, even if they pick the same version of bitflags. We'll
-            // want to make sure that e.g. a plugin and rustc each get their
+            // want to make sure that e.g., a plugin and rustc each get their
             // own copy of bitflags.
 
             // Cargo ensures that this works in general through the -C metadata

src/bootstrap/dist.rs

@@ -353,7 +353,7 @@ impl Step for Mingw {
     /// Build the `rust-mingw` installer component.
     ///
     /// This contains all the bits and pieces to run the MinGW Windows targets
-    /// without any extra installed software (e.g. we bundle gcc, libraries, etc).
+    /// without any extra installed software (e.g., we bundle gcc, libraries, etc).
     fn run(self, builder: &Builder) -> Option<PathBuf> {
         let host = self.host;
 

src/bootstrap/flags.rs

@@ -121,11 +121,11 @@ To learn more about a subcommand, run `./x.py <subcommand> -h`"
         opts.optopt("", "on-fail", "command to run on failure", "CMD");
         opts.optflag("", "dry-run", "dry run; don't build anything");
         opts.optopt("", "stage",
-            "stage to build (indicates compiler to use/test, e.g. stage 0 uses the \
+            "stage to build (indicates compiler to use/test, e.g., stage 0 uses the \
              bootstrap compiler, stage 1 the stage 0 rustc artifacts, etc.)",
             "N");
         opts.optmulti("", "keep-stage", "stage(s) to keep without recompiling \
-            (pass multiple times to keep e.g. both stages 0 and 1)", "N");
+            (pass multiple times to keep e.g., both stages 0 and 1)", "N");
         opts.optopt("", "src", "path to the root of the rust checkout", "DIR");
         opts.optopt("j", "jobs", "number of jobs to run in parallel", "JOBS");
         opts.optflag("h", "help", "print this help message");

src/bootstrap/job.rs

@@ -10,7 +10,7 @@
 
 //! Job management on Windows for bootstrapping
 //!
-//! Most of the time when you're running a build system (e.g. make) you expect
+//! Most of the time when you're running a build system (e.g., make) you expect
 //! Ctrl-C or abnormal termination to actually terminate the entire tree of
 //! process in play, not just the one at the top. This currently works "by
 //! default" on Unix platforms because Ctrl-C actually sends a signal to the
@@ -162,11 +162,11 @@ pub unsafe fn setup(build: &mut Build) {
         return
     }
 
-    // If we've got a parent process (e.g. the python script that called us)
+    // If we've got a parent process (e.g., the python script that called us)
     // then move ownership of this job object up to them. That way if the python
-    // script is killed (e.g. via ctrl-c) then we'll all be torn down.
+    // script is killed (e.g., via ctrl-c) then we'll all be torn down.
     //
-    // If we don't have a parent (e.g. this was run directly) then we
+    // If we don't have a parent (e.g., this was run directly) then we
     // intentionally leak the job object handle. When our process exits
     // (normally or abnormally) it will close the handle implicitly, causing all
     // processes in the job to be cleaned up.
@@ -184,7 +184,7 @@ pub unsafe fn setup(build: &mut Build) {
 
     // If this failed, well at least we tried! An example of DuplicateHandle
     // failing in the past has been when the wrong python2 package spawned this
-    // build system (e.g. the `python2` package in MSYS instead of
+    // build system (e.g., the `python2` package in MSYS instead of
     // `mingw-w64-x86_64-python2`. Not sure why it failed, but the "failure
     // mode" here is that we only clean everything up when the build system
     // dies, not when the python parent does, so not too bad.

src/bootstrap/lib.rs

@@ -38,7 +38,7 @@
 //! However, compiletest itself tries to avoid running tests when the artifacts
 //! that are involved (mainly the compiler) haven't changed.
 //!
-//! When you execute `x.py build`, the steps which are executed are:
+//! When you execute `x.py build`, the steps executed are:
 //!
 //! * First, the python script is run. This will automatically download the
 //!   stage0 rustc and cargo according to `src/stage0.txt`, or use the cached

src/bootstrap/native.rs

@@ -251,7 +251,7 @@ impl Step for Llvm {
         configure_cmake(builder, target, &mut cfg, false);
 
         // FIXME: we don't actually need to build all LLVM tools and all LLVM
-        //        libraries here, e.g. we just want a few components and a few
+        //        libraries here, e.g., we just want a few components and a few
         //        tools. Figure out how to filter them down and only build the right
         //        tools and libs on all platforms.
 

src/bootstrap/test.rs

@@ -971,7 +971,7 @@ impl Step for Compiletest {
         }
 
         if builder.no_std(target) == Some(true) {
-            // for no_std run-make (e.g. thumb*),
+            // for no_std run-make (e.g., thumb*),
             // we need a host compiler which is called by cargo.
             builder.ensure(compile::Std { compiler, target: compiler.host });
         }
@@ -1277,7 +1277,7 @@ impl Step for DocTest {
 
     /// Run `rustdoc --test` for all documentation in `src/doc`.
     ///
-    /// This will run all tests in our markdown documentation (e.g. the book)
+    /// This will run all tests in our markdown documentation (e.g., the book)
     /// located in `src/doc`. The `rustdoc` that's run is the one that sits next to
     /// `compiler`.
     fn run(self, builder: &Builder) {

src/bootstrap/tool.rs

@@ -646,7 +646,7 @@ impl<'a> Builder<'a> {
             self.cargo_out(compiler, tool.get_mode(), *host).join("deps"),
         ];
 
-        // On MSVC a tool may invoke a C compiler (e.g. compiletest in run-make
+        // On MSVC a tool may invoke a C compiler (e.g., compiletest in run-make
         // mode) and that C compiler may need some extra PATH modification. Do
         // so here.
         if compiler.host.contains("msvc") {

src/liballoc/boxed.rs

@@ -801,7 +801,7 @@ impl<T: ?Sized> AsMut<T> for Box<T> {
  *        safe.)
  *      - It is in practice very useful to have Box<T> be unconditionally
  *        Unpin because of trait objects, for which the structural auto
- *        trait functionality does not apply (e.g. Box<dyn Foo> would
+ *        trait functionality does not apply (e.g., Box<dyn Foo> would
  *        otherwise not be Unpin).
  *
  *  Another type with the same semantics as Box but only a conditional

src/liballoc/collections/binary_heap.rs

@@ -858,7 +858,7 @@ impl<T: Ord> BinaryHeap<T> {
     }
 }
 
-/// Hole represents a hole in a slice i.e. an index without valid value
+/// Hole represents a hole in a slice i.e., an index without valid value
 /// (because it was moved from or duplicated).
 /// In drop, `Hole` will restore the slice by filling the hole
 /// position with the value that was originally removed.

src/liballoc/collections/btree/set.rs

@@ -258,7 +258,7 @@ impl<T: Ord> BTreeSet<T> {
     }
 
     /// Visits the values representing the difference,
-    /// i.e. the values that are in `self` but not in `other`,
+    /// i.e., the values that are in `self` but not in `other`,
     /// in ascending order.
     ///
     /// # Examples
@@ -286,7 +286,7 @@ impl<T: Ord> BTreeSet<T> {
     }
 
     /// Visits the values representing the symmetric difference,
-    /// i.e. the values that are in `self` or in `other` but not in both,
+    /// i.e., the values that are in `self` or in `other` but not in both,
     /// in ascending order.
     ///
     /// # Examples
@@ -316,7 +316,7 @@ impl<T: Ord> BTreeSet<T> {
     }
 
     /// Visits the values representing the intersection,
-    /// i.e. the values that are both in `self` and `other`,
+    /// i.e., the values that are both in `self` and `other`,
     /// in ascending order.
     ///
     /// # Examples
@@ -344,7 +344,7 @@ impl<T: Ord> BTreeSet<T> {
     }
 
     /// Visits the values representing the union,
-    /// i.e. all the values in `self` or `other`, without duplicates,
+    /// i.e., all the values in `self` or `other`, without duplicates,
     /// in ascending order.
     ///
     /// # Examples
@@ -455,7 +455,7 @@ impl<T: Ord> BTreeSet<T> {
     }
 
     /// Returns `true` if the set is a subset of another,
-    /// i.e. `other` contains at least all the values in `self`.
+    /// i.e., `other` contains at least all the values in `self`.
     ///
     /// # Examples
     ///
@@ -498,7 +498,7 @@ impl<T: Ord> BTreeSet<T> {
     }
 
     /// Returns `true` if the set is a superset of another,
-    /// i.e. `self` contains at least all the values in `other`.
+    /// i.e., `self` contains at least all the values in `other`.
     ///
     /// # Examples
     ///

src/liballoc/raw_vec.rs

@@ -739,7 +739,7 @@ unsafe impl<#[may_dangle] T, A: Alloc> Drop for RawVec<T, A> {
 // On 64-bit we just need to check for overflow since trying to allocate
 // `> isize::MAX` bytes will surely fail. On 32-bit and 16-bit we need to add
 // an extra guard for this in case we're running on a platform which can use
-// all 4GB in user-space. e.g. PAE or x32
+// all 4GB in user-space. e.g., PAE or x32
 
 #[inline]
 fn alloc_guard(alloc_size: usize) -> Result<(), CollectionAllocErr> {

src/liballoc/rc.rs

@@ -276,7 +276,7 @@ struct RcBox<T: ?Sized> {
 /// See the [module-level documentation](./index.html) for more details.
 ///
 /// The inherent methods of `Rc` are all associated functions, which means
-/// that you have to call them as e.g. [`Rc::get_mut(&mut value)`][get_mut] instead of
+/// that you have to call them as e.g., [`Rc::get_mut(&mut value)`][get_mut] instead of
 /// `value.get_mut()`. This avoids conflicts with methods of the inner
 /// type `T`.
 ///
@@ -1252,7 +1252,7 @@ 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`
+    /// i.e., this `Weak` was created by `Weak::new`
     #[inline]
     fn inner(&self) -> Option<&RcBox<T>> {
         if is_dangling(self.ptr) {

src/liballoc/slice.rs

@@ -177,7 +177,7 @@ mod hack {
 impl<T> [T] {
     /// Sorts the slice.
     ///
-    /// This sort is stable (i.e. does not reorder equal elements) and `O(n log n)` worst-case.
+    /// This sort is stable (i.e., does not reorder equal elements) and `O(n log n)` worst-case.
     ///
     /// When applicable, unstable sorting is preferred because it is generally faster than stable
     /// sorting and it doesn't allocate auxiliary memory.
@@ -211,7 +211,7 @@ impl<T> [T] {
 
     /// 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.
+    /// This sort is stable (i.e., does not reorder equal elements) and `O(n log n)` worst-case.
     ///
     /// 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
@@ -264,7 +264,7 @@ impl<T> [T] {
 
     /// Sorts the slice with a key extraction function.
     ///
-    /// This sort is stable (i.e. does not reorder equal elements) and `O(m n log(m n))`
+    /// This sort is stable (i.e., does not reorder equal elements) and `O(m n log(m n))`
     /// worst-case, where the key function is `O(m)`.
     ///
     /// When applicable, unstable sorting is preferred because it is generally faster than stable
@@ -301,10 +301,10 @@ impl<T> [T] {
     ///
     /// During sorting, the key function is called only once per element.
     ///
-    /// This sort is stable (i.e. does not reorder equal elements) and `O(m n + n log n)`
+    /// This sort is stable (i.e., does not reorder equal elements) and `O(m n + n log n)`
     /// worst-case, where the key function is `O(m)`.
     ///
-    /// For simple key functions (e.g. functions that are property accesses or
+    /// For simple key functions (e.g., functions that are property accesses or
     /// basic operations), [`sort_by_key`](#method.sort_by_key) is likely to be
     /// faster.
     ///

src/liballoc/sync.rs

@@ -1121,7 +1121,7 @@ impl<T: ?Sized> Weak<T> {
     }
 
     /// Return `None` when the pointer is dangling and there is no allocated `ArcInner`,
-    /// i.e. this `Weak` was created by `Weak::new`
+    /// i.e., this `Weak` was created by `Weak::new`
     #[inline]
     fn inner(&self) -> Option<&ArcInner<T>> {
         if is_dangling(self.ptr) {

src/liballoc/tests/slice.rs

@@ -484,7 +484,7 @@ fn test_sort_stability() {
             // create a vector like [(6, 1), (5, 1), (6, 2), ...],
             // where the first item of each tuple is random, but
             // the second item represents which occurrence of that
-            // number this element is, i.e. the second elements
+            // number this element is, i.e., the second elements
             // will occur in sorted order.
             let mut orig: Vec<_> = (0..len)
                 .map(|_| {
@@ -502,7 +502,7 @@ fn test_sort_stability() {
             // This comparison includes the count (the second item
             // of the tuple), so elements with equal first items
             // will need to be ordered with increasing
-            // counts... i.e. exactly asserting that this sort is
+            // counts... i.e., exactly asserting that this sort is
             // stable.
             assert!(v.windows(2).all(|w| w[0] <= w[1]));
 
@@ -1579,7 +1579,7 @@ macro_rules! test {
             }).join();
 
             // Check that the number of things dropped is exactly
-            // what we expect (i.e. the contents of `v`).
+            // what we expect (i.e., the contents of `v`).
             for (i, c) in DROP_COUNTS.iter().enumerate().take(len) {
                 let count = c.load(Relaxed);
                 assert!(count == 1,

src/liballoc/tests/str.rs

@@ -1005,7 +1005,7 @@ fn test_escape_debug() {
     // Note that there are subtleties with the number of backslashes
     // on the left- and right-hand sides. In particular, Unicode code points
     // are usually escaped with two backslashes on the right-hand side, as
-    // they are escaped. However, when the character is unescaped (e.g. for
+    // they are escaped. However, when the character is unescaped (e.g., for
     // printable characters), only a single backslash appears (as the character
     // itself appears in the debug string).
     assert_eq!("abc".escape_debug(), "abc");

src/liballoc/vec.rs

@@ -213,7 +213,7 @@ use raw_vec::RawVec;
 /// about its design. This ensures that it's as low-overhead as possible in
 /// the general case, and can be correctly manipulated in primitive ways
 /// by unsafe code. Note that these guarantees refer to an unqualified `Vec<T>`.
-/// If additional type parameters are added (e.g. to support custom allocators),
+/// If additional type parameters are added (e.g., to support custom allocators),
 /// overriding their defaults may change the behavior.
 ///
 /// Most fundamentally, `Vec` is and always will be a (pointer, capacity, length)

src/libcore/alloc.rs

@@ -69,7 +69,7 @@ impl Layout {
     /// * `align` must be a power of two,
     ///
     /// * `size`, when rounded up to the nearest multiple of `align`,
-    ///    must not overflow (i.e. the rounded value must be less than
+    ///    must not overflow (i.e., the rounded value must be less than
     ///    `usize::MAX`).
     #[stable(feature = "alloc_layout", since = "1.28.0")]
     #[inline]
@@ -177,7 +177,7 @@ impl Layout {
     /// to ensure that the following address will satisfy `align`
     /// (measured in bytes).
     ///
-    /// E.g. if `self.size()` is 9, then `self.padding_needed_for(4)`
+    /// e.g., if `self.size()` is 9, then `self.padding_needed_for(4)`
     /// returns 3, because that is the minimum number of bytes of
     /// padding required to get a 4-aligned address (assuming that the
     /// corresponding memory block starts at a 4-aligned address).
@@ -455,7 +455,7 @@ pub unsafe trait GlobalAlloc {
     /// if the caller does not ensure that `layout` has non-zero size.
     ///
     /// (Extension subtraits might provide more specific bounds on
-    /// behavior, e.g. guarantee a sentinel address or a null pointer
+    /// behavior, e.g., guarantee a sentinel address or a null pointer
     /// in response to a zero-size allocation request.)
     ///
     /// The allocated block of memory may or may not be initialized.
@@ -550,10 +550,10 @@ pub unsafe trait GlobalAlloc {
     /// * `new_size` must be greater than zero.
     ///
     /// * `new_size`, when rounded up to the nearest multiple of `layout.align()`,
-    ///   must not overflow (i.e. the rounded value must be less than `usize::MAX`).
+    ///   must not overflow (i.e., the rounded value must be less than `usize::MAX`).
     ///
     /// (Extension subtraits might provide more specific bounds on
-    /// behavior, e.g. guarantee a sentinel address or a null pointer
+    /// behavior, e.g., guarantee a sentinel address or a null pointer
     /// in response to a zero-size allocation request.)
     ///
     /// # Errors
@@ -616,7 +616,7 @@ pub unsafe trait GlobalAlloc {
 ///   whether to return `Err`, or to return `Ok` with some pointer.
 ///
 /// * If an `Alloc` implementation chooses to return `Ok` in this
-///   case (i.e. the pointer denotes a zero-sized inaccessible block)
+///   case (i.e., the pointer denotes a zero-sized inaccessible block)
 ///   then that returned pointer must be considered "currently
 ///   allocated". On such an allocator, *all* methods that take
 ///   currently-allocated pointers as inputs must accept these
@@ -651,7 +651,7 @@ pub unsafe trait GlobalAlloc {
 ///
 ///  * if a layout `k` fits a memory block (denoted by `ptr`)
 ///    currently allocated via an allocator `a`, then it is legal to
-///    use that layout to deallocate it, i.e. `a.dealloc(ptr, k);`.
+///    use that layout to deallocate it, i.e., `a.dealloc(ptr, k);`.
 ///
 /// # Unsafety
 ///
@@ -673,7 +673,7 @@ pub unsafe trait Alloc {
 
     // (Note: some existing allocators have unspecified but well-defined
     // behavior in response to a zero size allocation request ;
-    // e.g. in C, `malloc` of 0 will either return a null pointer or a
+    // e.g., in C, `malloc` of 0 will either return a null pointer or a
     // unique pointer, but will not have arbitrary undefined
     // behavior.
     // However in jemalloc for example,
@@ -688,7 +688,7 @@ pub unsafe trait Alloc {
     ///
     /// The returned block of storage may or may not have its contents
     /// initialized. (Extension subtraits might restrict this
-    /// behavior, e.g. to ensure initialization to particular sets of
+    /// behavior, e.g., to ensure initialization to particular sets of
     /// bit patterns.)
     ///
     /// # Safety
@@ -697,7 +697,7 @@ pub unsafe trait Alloc {
     /// if the caller does not ensure that `layout` has non-zero size.
     ///
     /// (Extension subtraits might provide more specific bounds on
-    /// behavior, e.g. guarantee a sentinel address or a null pointer
+    /// behavior, e.g., guarantee a sentinel address or a null pointer
     /// in response to a zero-size allocation request.)
     ///
     /// # Errors
@@ -803,10 +803,10 @@ pub unsafe trait Alloc {
     /// * `new_size` must be greater than zero.
     ///
     /// * `new_size`, when rounded up to the nearest multiple of `layout.align()`,
-    ///   must not overflow (i.e. the rounded value must be less than `usize::MAX`).
+    ///   must not overflow (i.e., the rounded value must be less than `usize::MAX`).
     ///
     /// (Extension subtraits might provide more specific bounds on
-    /// behavior, e.g. guarantee a sentinel address or a null pointer
+    /// behavior, e.g., guarantee a sentinel address or a null pointer
     /// in response to a zero-size allocation request.)
     ///
     /// # Errors

src/libcore/any.rs

@@ -126,7 +126,7 @@ impl fmt::Debug for dyn Any {
     }
 }
 
-// Ensure that the result of e.g. joining a thread can be printed and
+// Ensure that the result of e.g., joining a thread can be printed and
 // hence used with `unwrap`. May eventually no longer be needed if
 // dispatch works with upcasting.
 #[stable(feature = "rust1", since = "1.0.0")]

src/libcore/cell.rs

@@ -97,7 +97,7 @@
 //! ## Implementation details of logically-immutable methods
 //!
 //! Occasionally it may be desirable not to expose in an API that there is mutation happening
-//! "under the hood". This may be because logically the operation is immutable, but e.g. caching
+//! "under the hood". This may be because logically the operation is immutable, but e.g., caching
 //! forces the implementation to perform mutation; or because you must employ mutation to implement
 //! a trait method that was originally defined to take `&self`.
 //!
@@ -1227,7 +1227,7 @@ impl<T: ?Sized + fmt::Display> fmt::Display for Ref<'_, T> {
 }
 
 impl<'b, T: ?Sized> RefMut<'b, T> {
-    /// Make a new `RefMut` for a component of the borrowed data, e.g. an enum
+    /// Make a new `RefMut` for a component of the borrowed data, e.g., an enum
     /// variant.
     ///
     /// The `RefCell` is already mutably borrowed, so this cannot fail.

src/libcore/char/mod.rs

@@ -131,7 +131,7 @@ pub struct EscapeUnicode {
     state: EscapeUnicodeState,
 
     // The index of the next hex digit to be printed (0 if none),
-    // i.e. the number of remaining hex digits to be printed;
+    // i.e., the number of remaining hex digits to be printed;
     // increasing from the least significant digit: 0x543210
     hex_digit_idx: usize,
 }

src/libcore/clone.rs

@@ -13,7 +13,7 @@
 //! In Rust, some simple types are "implicitly copyable" and when you
 //! assign them or pass them as arguments, the receiver will get a copy,
 //! leaving the original value in place. These types do not require
-//! allocation to copy and do not have finalizers (i.e. they do not
+//! allocation to copy and do not have finalizers (i.e., they do not
 //! contain owned boxes or implement [`Drop`]), so the compiler considers
 //! them cheap and safe to copy. For other types copies must be made
 //! explicitly, by convention implementing the [`Clone`] trait and calling
@@ -93,10 +93,10 @@
 /// In addition to the [implementors listed below][impls],
 /// the following types also implement `Clone`:
 ///
-/// * Function item types (i.e. the distinct types defined for each function)
+/// * Function item types (i.e., the distinct types defined for each function)
-/// * Function pointer types (e.g. `fn() -> i32`)
+/// * Function pointer types (e.g., `fn() -> i32`)
-/// * Array types, for all sizes, if the item type also implements `Clone` (e.g. `[i32; 123456]`)
+/// * Array types, for all sizes, if the item type also implements `Clone` (e.g., `[i32; 123456]`)
-/// * Tuple types, if each component also implements `Clone` (e.g. `()`, `(i32, bool)`)
+/// * Tuple types, if each component also implements `Clone` (e.g., `()`, `(i32, bool)`)
 /// * Closure types, if they capture no value from the environment
 ///   or if all such captured values implement `Clone` themselves.
 ///   Note that variables captured by shared reference always implement `Clone`

src/libcore/ffi.rs

@@ -18,7 +18,7 @@ use ::fmt;
 ///
 /// [`!`]: ../../std/primitive.never.html
 /// [pointer]: ../../std/primitive.pointer.html
-// NB: For LLVM to recognize the void pointer type and by extension
+// N.B., for LLVM to recognize the void pointer type and by extension
 //     functions like malloc(), we need to have it represented as i8* in
 //     LLVM bitcode. The enum used here ensures this and prevents misuse
 //     of the "raw" type by only having private variants.. We need two

src/libcore/hash/mod.rs

@@ -408,7 +408,7 @@ impl<H: Hasher + ?Sized> Hasher for &mut H {
 
 /// A trait for creating instances of [`Hasher`].
 ///
-/// A `BuildHasher` is typically used (e.g. by [`HashMap`]) to create
+/// A `BuildHasher` is typically used (e.g., by [`HashMap`]) to create
 /// [`Hasher`]s for each key such that they are hashed independently of one
 /// another, since [`Hasher`]s contain state.
 ///

src/libcore/hint.rs

@@ -24,7 +24,7 @@ use intrinsics;
 /// therefore will eliminate all branches that reach to a call to
 /// `unreachable_unchecked()`.
 ///
-/// Like all instances of UB, if this assumption turns out to be wrong, i.e. the
+/// Like all instances of UB, if this assumption turns out to be wrong, i.e., the
 /// `unreachable_unchecked()` call is actually reachable among all possible
 /// control flow, the compiler will apply the wrong optimization strategy, and
 /// may sometimes even corrupt seemingly unrelated code, causing

src/libcore/intrinsics.rs

@@ -52,7 +52,7 @@
 pub use ptr::drop_in_place;
 
 extern "rust-intrinsic" {
-    // NB: These intrinsics take raw pointers because they mutate aliased
+    // N.B., these intrinsics take raw pointers because they mutate aliased
     // memory, which is not valid for either `&` or `&mut`.
 
     /// Stores a value if the current value is the same as the `old` value.
@@ -635,7 +635,7 @@ extern "rust-intrinsic" {
     /// Tells LLVM that this point in the code is not reachable, enabling
     /// further optimizations.
     ///
-    /// NB: This is very different from the `unreachable!()` macro: Unlike the
+    /// N.B., this is very different from the `unreachable!()` macro: Unlike the
     /// macro, which panics when it is executed, it is *undefined behavior* to
     /// reach code marked with this function.
     ///

src/libcore/iter/iterator.rs

@@ -154,7 +154,7 @@ pub trait Iterator {
     ///
     /// `size_hint()` is primarily intended to be used for optimizations such as
     /// reserving space for the elements of the iterator, but must not be
-    /// trusted to e.g. omit bounds checks in unsafe code. An incorrect
+    /// trusted to e.g., omit bounds checks in unsafe code. An incorrect
     /// implementation of `size_hint()` should not lead to memory safety
     /// violations.
     ///

src/libcore/iter/traits.rs

@@ -770,7 +770,7 @@ pub trait Product<A = Self>: Sized {
     fn product<I: Iterator<Item=A>>(iter: I) -> Self;
 }
 
-// NB: explicitly use Add and Mul here to inherit overflow checks
+// N.B., explicitly use Add and Mul here to inherit overflow checks
 macro_rules! integer_sum_product {
     (@impls $zero:expr, $one:expr, #[$attr:meta], $($a:ty)*) => ($(
         #[$attr]

src/libcore/marker.rs

@@ -274,10 +274,10 @@ pub trait Unsize<T: ?Sized> {
 /// In addition to the [implementors listed below][impls],
 /// the following types also implement `Copy`:
 ///
-/// * Function item types (i.e. the distinct types defined for each function)
+/// * Function item types (i.e., the distinct types defined for each function)
-/// * Function pointer types (e.g. `fn() -> i32`)
+/// * Function pointer types (e.g., `fn() -> i32`)
-/// * Array types, for all sizes, if the item type also implements `Copy` (e.g. `[i32; 123456]`)
+/// * Array types, for all sizes, if the item type also implements `Copy` (e.g., `[i32; 123456]`)
-/// * Tuple types, if each component also implements `Copy` (e.g. `()`, `(i32, bool)`)
+/// * Tuple types, if each component also implements `Copy` (e.g., `()`, `(i32, bool)`)
 /// * Closure types, if they capture no value from the environment
 ///   or if all such captured values implement `Copy` themselves.
 ///   Note that variables captured by shared reference always implement `Copy`

src/libcore/mem.rs

@@ -305,7 +305,7 @@ pub const fn size_of<T>() -> usize {
 /// Returns the size of the pointed-to value in bytes.
 ///
 /// This is usually the same as `size_of::<T>()`. However, when `T` *has* no
-/// statically known size, e.g. a slice [`[T]`][slice] or a [trait object],
+/// statically known size, e.g., a slice [`[T]`][slice] or a [trait object],
 /// then `size_of_val` can be used to get the dynamically-known size.
 ///
 /// [slice]: ../../std/primitive.slice.html
@@ -1119,7 +1119,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/bignum.rs

@@ -183,7 +183,7 @@ macro_rules! define_bignum {
                 let nonzero = &digits[..end];
 
                 if nonzero.is_empty() {
-                    // There are no non-zero digits, i.e. the number is zero.
+                    // There are no non-zero digits, i.e., the number is zero.
                     return 0;
                 }
                 // This could be optimized with leading_zeros() and bit shifts, but that's

src/libcore/num/dec2flt/algorithm.rs

@@ -61,9 +61,9 @@ mod fpu_precision {
     ///
     /// The only field which is relevant for the following code is PC, Precision Control. This
     /// field determines the precision of the operations performed by the  FPU. It can be set to:
-    ///  - 0b00, single precision i.e. 32-bits
+    ///  - 0b00, single precision i.e., 32-bits
-    ///  - 0b10, double precision i.e. 64-bits
+    ///  - 0b10, double precision i.e., 64-bits
-    ///  - 0b11, double extended precision i.e. 80-bits (default state)
+    ///  - 0b11, double extended precision i.e., 80-bits (default state)
     /// The 0b01 value is reserved and should not be used.
     pub struct FPUControlWord(u16);
 

src/libcore/num/dec2flt/rawfp.rs

@@ -349,7 +349,7 @@ pub fn prev_float<T: RawFloat>(x: T) -> T {
 }
 
 // Find the smallest floating point number strictly larger than the argument.
-// This operation is saturating, i.e. next_float(inf) == inf.
+// This operation is saturating, i.e., next_float(inf) == inf.
 // Unlike most code in this module, this function does handle zero, subnormals, and infinities.
 // However, like all other code here, it does not deal with NaN and negative numbers.
 pub fn next_float<T: RawFloat>(x: T) -> T {

src/libcore/num/flt2dec/mod.rs

@@ -23,7 +23,7 @@ representation `V = 0.d[0..n-1] * 10^k` such that:
 - `d[0]` is non-zero.
 
 - It's correctly rounded when parsed back: `v - minus < V < v + plus`.
-  Furthermore it is shortest such one, i.e. there is no representation
+  Furthermore it is shortest such one, i.e., there is no representation
   with less than `n` digits that is correctly rounded.
 
 - It's closest to the original value: `abs(V - v) <= 10^(k-n) / 2`. Note that
@@ -398,7 +398,7 @@ fn determine_sign(sign: Sign, decoded: &FullDecoded, negative: bool) -> &'static
 /// given number of fractional digits. The result is stored to the supplied parts
 /// array while utilizing given byte buffer as a scratch. `upper` is currently
 /// unused but left for the future decision to change the case of non-finite values,
-/// i.e. `inf` and `nan`. The first part to be rendered is always a `Part::Sign`
+/// i.e., `inf` and `nan`. The first part to be rendered is always a `Part::Sign`
 /// (which can be an empty string if no sign is rendered).
 ///
 /// `format_shortest` should be the underlying digit-generation function.
@@ -591,7 +591,7 @@ pub fn to_exact_exp_str<'a, T, F>(mut format_exact: F, v: T,
 /// given number of fractional digits. The result is stored to the supplied parts
 /// array while utilizing given byte buffer as a scratch. `upper` is currently
 /// unused but left for the future decision to change the case of non-finite values,
-/// i.e. `inf` and `nan`. The first part to be rendered is always a `Part::Sign`
+/// i.e., `inf` and `nan`. The first part to be rendered is always a `Part::Sign`
 /// (which can be an empty string if no sign is rendered).
 ///
 /// `format_exact` should be the underlying digit-generation function.

src/libcore/num/flt2dec/strategy/dragon.rs

@@ -81,11 +81,11 @@ pub fn format_shortest(d: &Decoded, buf: &mut [u8]) -> (/*#digits*/ usize, /*exp
     // - followed by `(mant + 2 * plus) * 2^exp` in the original type.
     //
     // obviously, `minus` and `plus` cannot be zero. (for infinities, we use out-of-range values.)
-    // also we assume that at least one digit is generated, i.e. `mant` cannot be zero too.
+    // also we assume that at least one digit is generated, i.e., `mant` cannot be zero too.
     //
     // this also means that any number between `low = (mant - minus) * 2^exp` and
     // `high = (mant + plus) * 2^exp` will map to this exact floating point number,
-    // with bounds included when the original mantissa was even (i.e. `!mant_was_odd`).
+    // with bounds included when the original mantissa was even (i.e., `!mant_was_odd`).
 
     assert!(d.mant > 0);
     assert!(d.minus > 0);
@@ -172,7 +172,7 @@ pub fn format_shortest(d: &Decoded, buf: &mut [u8]) -> (/*#digits*/ usize, /*exp
         // - `high - v = plus / scale * 10^(k-n)`
         //
         // assume that `d[0..n-1]` is the shortest representation between `low` and `high`,
-        // i.e. `d[0..n-1]` satisfies both of the following but `d[0..n-2]` doesn't:
+        // i.e., `d[0..n-1]` satisfies both of the following but `d[0..n-2]` doesn't:
         // - `low < d[0..n-1] * 10^(k-n) < high` (bijectivity: digits round to `v`); and
         // - `abs(v / 10^(k-n) - d[0..n-1]) <= 1/2` (the last digit is correct).
         //
@@ -304,7 +304,7 @@ pub fn format_exact(d: &Decoded, buf: &mut [u8], limit: i16) -> (/*#digits*/ usi
 
     // rounding up if we stop in the middle of digits
     // if the following digits are exactly 5000..., check the prior digit and try to
-    // round to even (i.e. avoid rounding up when the prior digit is even).
+    // round to even (i.e., avoid rounding up when the prior digit is even).
     let order = mant.cmp(scale.mul_small(5));
     if order == Ordering::Greater || (order == Ordering::Equal &&
                                       (len == 0 || buf[len-1] & 1 == 1)) {

src/libcore/num/flt2dec/strategy/grisu.rs

@@ -242,7 +242,7 @@ pub fn format_shortest_opt(d: &Decoded,
     //
     // find the digit length `kappa` between `(minus1, plus1)` as per Theorem 6.2.
     // Theorem 6.2 can be adopted to exclude `x` by requiring `y mod 10^k < y - x` instead.
-    // (e.g. `x` = 32000, `y` = 32777; `kappa` = 2 since `y mod 10^3 = 777 < y - x = 777`.)
+    // (e.g., `x` = 32000, `y` = 32777; `kappa` = 2 since `y mod 10^3 = 777 < y - x = 777`.)
     // the algorithm relies on the later verification phase to exclude `y`.
     let delta1 = plus1 - minus1;
 //  let delta1int = (delta1 >> e) as usize; // only for explanation
@@ -362,19 +362,19 @@ pub fn format_shortest_opt(d: &Decoded,
             // proceed, but we then have at least one valid representation known to be closest to
             // `v + 1 ulp` anyway. we will denote them as TC1 through TC3 for brevity.
             //
-            // TC1: `w(n) <= v + 1 ulp`, i.e. this is the last repr that can be the closest one.
+            // TC1: `w(n) <= v + 1 ulp`, i.e., this is the last repr that can be the closest one.
             // this is equivalent to `plus1 - w(n) = plus1w(n) >= plus1 - (v + 1 ulp) = plus1v_up`.
             // combined with TC2 (which checks if `w(n+1)` is valid), this prevents the possible
             // overflow on the calculation of `plus1w(n)`.
             //
-            // TC2: `w(n+1) < minus1`, i.e. the next repr definitely does not round to `v`.
+            // TC2: `w(n+1) < minus1`, i.e., the next repr definitely does not round to `v`.
             // this is equivalent to `plus1 - w(n) + 10^kappa = plus1w(n) + 10^kappa >
             // plus1 - minus1 = threshold`. the left hand side can overflow, but we know
             // `threshold > plus1v`, so if TC1 is false, `threshold - plus1w(n) >
             // threshold - (plus1v - 1 ulp) > 1 ulp` and we can safely test if
             // `threshold - plus1w(n) < 10^kappa` instead.
             //
-            // TC3: `abs(w(n) - (v + 1 ulp)) <= abs(w(n+1) - (v + 1 ulp))`, i.e. the next repr is
+            // TC3: `abs(w(n) - (v + 1 ulp)) <= abs(w(n+1) - (v + 1 ulp))`, i.e., the next repr is
             // no closer to `v + 1 ulp` than the current repr. given `z(n) = plus1v_up - plus1w(n)`,
             // this becomes `abs(z(n)) <= abs(z(n+1))`. again assuming that TC1 is false, we have
             // `z(n) > 0`. we have two cases to consider:
@@ -384,7 +384,7 @@ pub fn format_shortest_opt(d: &Decoded,
             // - when `z(n+1) < 0`:
             //   - TC3a: the precondition is `plus1v_up < plus1w(n) + 10^kappa`. assuming TC2 is
             //     false, `threshold >= plus1w(n) + 10^kappa` so it cannot overflow.
-            //   - TC3b: TC3 becomes `z(n) <= -z(n+1)`, i.e. `plus1v_up - plus1w(n) >=
+            //   - TC3b: TC3 becomes `z(n) <= -z(n+1)`, i.e., `plus1v_up - plus1w(n) >=
             //     plus1w(n+1) - plus1v_up = plus1w(n) + 10^kappa - plus1v_up`. the negated TC1
             //     gives `plus1v_up > plus1w(n)`, so it cannot overflow or underflow when
             //     combined with TC3a.
@@ -414,7 +414,7 @@ pub fn format_shortest_opt(d: &Decoded,
 
         // now we have the closest representation to `v` between `plus1` and `minus1`.
         // this is too liberal, though, so we reject any `w(n)` not between `plus0` and `minus0`,
-        // i.e. `plus1 - plus1w(n) <= minus0` or `plus1 - plus1w(n) >= plus0`. we utilize the facts
+        // i.e., `plus1 - plus1w(n) <= minus0` or `plus1 - plus1w(n) >= plus0`. we utilize the facts
         // that `threshold = plus1 - minus1` and `plus1 - plus0 = minus0 - minus1 = 2 ulp`.
         if 2 * ulp <= plus1w && plus1w <= threshold - 4 * ulp {
             Some((buf.len(), exp))
@@ -675,7 +675,7 @@ pub fn format_exact_opt(d: &Decoded, buf: &mut [u8], limit: i16)
             return Some((len, exp));
         }
 
-        // otherwise we are doomed (i.e. some values between `v - 1 ulp` and `v + 1 ulp` are
+        // otherwise we are doomed (i.e., some values between `v - 1 ulp` and `v + 1 ulp` are
         // rounding down and others are rounding up) and give up.
         None
     }

src/libcore/num/mod.rs

@@ -1544,7 +1544,7 @@ assert_eq!(", stringify!($SelfT), "::MIN.overflowing_mod_euc(-1), (0, true));
             concat!("Negates self, overflowing if this is equal to the minimum value.
 
 Returns a tuple of the negated version of self along with a boolean indicating whether an overflow
-happened. If `self` is the minimum value (e.g. `i32::MIN` for values of type `i32`), then the
+happened. If `self` is the minimum value (e.g., `i32::MIN` for values of type `i32`), then the
 minimum value will be returned again and `true` will be returned for an overflow happening.
 
 # Examples
@@ -1621,7 +1621,7 @@ $EndFeature, "
             concat!("Computes the absolute value of `self`.
 
 Returns a tuple of the absolute version of self along with a boolean indicating whether an overflow
-happened. If self is the minimum value (e.g. ", stringify!($SelfT), "::MIN for values of type
+happened. If self is the minimum value (e.g., ", stringify!($SelfT), "::MIN for values of type
  ", stringify!($SelfT), "), then the minimum value will be returned again and true will be returned
 for an overflow happening.
 
@@ -3617,7 +3617,7 @@ assert!(!10", stringify!($SelfT), ".is_power_of_two());", $EndFeature, "
         doc_comment! {
             concat!("Returns the smallest power of two greater than or equal to `self`.
 
-When return value overflows (i.e. `self > (1 << (N-1))` for type
+When return value overflows (i.e., `self > (1 << (N-1))` for type
 `uN`), it panics in debug mode and return value is wrapped to 0 in
 release mode (the only situation in which method can return 0).
 
@@ -4827,7 +4827,7 @@ fn from_str_radix<T: FromStrRadixHelper>(src: &str, radix: u32) -> Result<T, Par
 /// # Potential causes
 ///
 /// Among other causes, `ParseIntError` can be thrown because of leading or trailing whitespace
-/// in the string e.g. when it is obtained from the standard input.
+/// in the string e.g., when it is obtained from the standard input.
 /// Using the [`str.trim()`] method ensures that no whitespace remains before parsing.
 ///
 /// [`str.trim()`]: ../../std/primitive.str.html#method.trim

src/libcore/num/wrapping.rs

@@ -865,7 +865,7 @@ assert!(!Wrapping(10", stringify!($t), ").is_power_of_two());
             doc_comment! {
                 concat!("Returns the smallest power of two greater than or equal to `self`.
 
-When return value overflows (i.e. `self > (1 << (N-1))` for type
+When return value overflows (i.e., `self > (1 << (N-1))` for type
 `uN`), overflows to `2^N = 0`.
 
 # Examples

src/libcore/ops/function.rs

@@ -26,7 +26,7 @@
 /// is expected.
 ///
 /// Use `Fn` as a bound when you want to accept a parameter of function-like
-/// type and need to call it repeatedly and without mutating state (e.g. when
+/// type and need to call it repeatedly and without mutating state (e.g., when
 /// calling it concurrently). If you do not need such strict requirements, use
 /// [`FnMut`] or [`FnOnce`] as bounds.
 ///
@@ -84,7 +84,7 @@ pub trait Fn<Args> : FnMut<Args> {
 ///
 /// `FnMut` is implemented automatically by closures which take mutable
 /// references to captured variables, as well as all types that implement
-/// [`Fn`], e.g. (safe) [function pointers][] (since `FnMut` is a supertrait of
+/// [`Fn`], e.g., (safe) [function pointers][] (since `FnMut` is a supertrait of
 /// [`Fn`]). Additionally, for any type `F` that implements `FnMut`, `&mut F`
 /// implements `FnMut`, too.
 ///
@@ -163,7 +163,7 @@ pub trait FnMut<Args> : FnOnce<Args> {
 /// implements `FnOnce`, it can only be called once.
 ///
 /// `FnOnce` is implemented automatically by closure that might consume captured
-/// variables, as well as all types that implement [`FnMut`], e.g. (safe)
+/// variables, as well as all types that implement [`FnMut`], e.g., (safe)
 /// [function pointers][] (since `FnOnce` is a supertrait of [`FnMut`]).
 ///
 /// Since both [`Fn`] and [`FnMut`] are subtraits of `FnOnce`, any instance of

src/libcore/ops/mod.rs

@@ -27,7 +27,7 @@
 //! should have some resemblance to multiplication (and share expected
 //! properties like associativity).
 //!
-//! Note that the `&&` and `||` operators short-circuit, i.e. they only
+//! Note that the `&&` and `||` operators short-circuit, i.e., they only
 //! evaluate their second operand if it contributes to the result. Since this
 //! behavior is not enforceable by traits, `&&` and `||` are not supported as
 //! overloadable operators.

src/libcore/option.rs

@@ -62,7 +62,7 @@
 //! The following example uses [`Option`] to create an optional box of
 //! [`i32`]. Notice that in order to use the inner [`i32`] value first, the
 //! `check_optional` function needs to use pattern matching to
-//! determine whether the box has a value (i.e. it is [`Some(...)`][`Some`]) or
+//! determine whether the box has a value (i.e., it is [`Some(...)`][`Some`]) or
 //! not ([`None`]).
 //!
 //! ```

src/libcore/pin.rs

@@ -9,7 +9,7 @@
 //!
 //! In order to prevent objects from moving, they must be pinned
 //! by wrapping a pointer to the data in the [`Pin`] type. A pointer wrapped
-//! in a `Pin` is otherwise equivalent to its normal version, e.g. `Pin<Box<T>>`
+//! in a `Pin` is otherwise equivalent to its normal version, e.g., `Pin<Box<T>>`
 //! and `Box<T>` work the same way except that the first is pinning the value
 //! of `T` in place.
 //!

src/libcore/ptr.rs

@@ -103,7 +103,7 @@ pub use intrinsics::write_bytes;
 ///   dropped normally.
 ///
 /// * It is friendlier to the optimizer to do this over [`ptr::read`] when
-///   dropping manually allocated memory (e.g. when writing Box/Rc/Vec),
+///   dropping manually allocated memory (e.g., when writing Box/Rc/Vec),
 ///   as the compiler doesn't need to prove that it's sound to elide the
 ///   copy.
 ///
@@ -836,7 +836,7 @@ pub unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
 ///
 /// The compiler shouldn't change the relative order or number of volatile
 /// memory operations. However, volatile memory operations on zero-sized types
-/// (e.g. if a zero-sized type is passed to `read_volatile`) are no-ops
+/// (e.g., if a zero-sized type is passed to `read_volatile`) are no-ops
 /// and may be ignored.
 ///
 /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
@@ -913,7 +913,7 @@ pub unsafe fn read_volatile<T>(src: *const T) -> T {
 ///
 /// The compiler shouldn't change the relative order or number of volatile
 /// memory operations. However, volatile memory operations on zero-sized types
-/// (e.g. if a zero-sized type is passed to `write_volatile`) are no-ops
+/// (e.g., if a zero-sized type is passed to `write_volatile`) are no-ops
 /// and may be ignored.
 ///
 /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
@@ -1035,7 +1035,7 @@ impl<T: ?Sized> *const T {
 
     /// Calculates the offset from a pointer.
     ///
-    /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
+    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
     /// offset of `3 * size_of::<T>()` bytes.
     ///
     /// # Safety
@@ -1089,7 +1089,7 @@ impl<T: ?Sized> *const T {
 
     /// Calculates the offset from a pointer using wrapping arithmetic.
     ///
-    /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
+    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
     /// offset of `3 * size_of::<T>()` bytes.
     ///
     /// # Safety
@@ -1253,7 +1253,7 @@ impl<T: ?Sized> *const T {
 
     /// Calculates the offset from a pointer (convenience for `.offset(count as isize)`).
     ///
-    /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
+    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
     /// offset of `3 * size_of::<T>()` bytes.
     ///
     /// # Safety
@@ -1310,7 +1310,7 @@ impl<T: ?Sized> *const T {
     /// Calculates the offset from a pointer (convenience for
     /// `.offset((count as isize).wrapping_neg())`).
     ///
-    /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
+    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
     /// offset of `3 * size_of::<T>()` bytes.
     ///
     /// # Safety
@@ -1367,7 +1367,7 @@ impl<T: ?Sized> *const T {
     /// Calculates the offset from a pointer using wrapping arithmetic.
     /// (convenience for `.wrapping_offset(count as isize)`)
     ///
-    /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
+    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
     /// offset of `3 * size_of::<T>()` bytes.
     ///
     /// # Safety
@@ -1408,7 +1408,7 @@ impl<T: ?Sized> *const T {
     /// Calculates the offset from a pointer using wrapping arithmetic.
     /// (convenience for `.wrapping_offset((count as isize).wrapping_sub())`)
     ///
-    /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
+    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
     /// offset of `3 * size_of::<T>()` bytes.
     ///
     /// # Safety
@@ -1655,7 +1655,7 @@ impl<T: ?Sized> *mut T {
 
     /// Calculates the offset from a pointer.
     ///
-    /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
+    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
     /// offset of `3 * size_of::<T>()` bytes.
     ///
     /// # Safety
@@ -1708,7 +1708,7 @@ impl<T: ?Sized> *mut T {
     }
 
     /// Calculates the offset from a pointer using wrapping arithmetic.
-    /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
+    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
     /// offset of `3 * size_of::<T>()` bytes.
     ///
     /// # Safety
@@ -1891,7 +1891,7 @@ impl<T: ?Sized> *mut T {
 
     /// Calculates the offset from a pointer (convenience for `.offset(count as isize)`).
     ///
-    /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
+    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
     /// offset of `3 * size_of::<T>()` bytes.
     ///
     /// # Safety
@@ -1948,7 +1948,7 @@ impl<T: ?Sized> *mut T {
     /// Calculates the offset from a pointer (convenience for
     /// `.offset((count as isize).wrapping_neg())`).
     ///
-    /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
+    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
     /// offset of `3 * size_of::<T>()` bytes.
     ///
     /// # Safety
@@ -2005,7 +2005,7 @@ impl<T: ?Sized> *mut T {
     /// Calculates the offset from a pointer using wrapping arithmetic.
     /// (convenience for `.wrapping_offset(count as isize)`)
     ///
-    /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
+    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
     /// offset of `3 * size_of::<T>()` bytes.
     ///
     /// # Safety
@@ -2046,7 +2046,7 @@ impl<T: ?Sized> *mut T {
     /// Calculates the offset from a pointer using wrapping arithmetic.
     /// (convenience for `.wrapping_offset((count as isize).wrapping_sub())`)
     ///
-    /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
+    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
     /// offset of `3 * size_of::<T>()` bytes.
     ///
     /// # Safety
@@ -2375,7 +2375,7 @@ pub(crate) unsafe fn align_offset<T: Sized>(p: *const T, a: usize) -> usize {
     fn mod_inv(x: usize, m: usize) -> usize {
         /// Multiplicative modular inverse table modulo 2⁴ = 16.
         ///
-        /// Note, that this table does not contain values where inverse does not exist (i.e. for
+        /// Note, that this table does not contain values where inverse does not exist (i.e., for
         /// `0⁻¹ mod 16`, `2⁻¹ mod 16`, etc.)
         const INV_TABLE_MOD_16: [u8; 8] = [1, 11, 13, 7, 9, 3, 5, 15];
         /// Modulo for which the `INV_TABLE_MOD_16` is intended.
@@ -2398,7 +2398,7 @@ pub(crate) unsafe fn align_offset<T: Sized>(p: *const T, a: usize) -> usize {
                 // y = y * (2 - xy) mod n
                 //
                 // Note, that we use wrapping operations here intentionally – the original formula
-                // uses e.g. subtraction `mod n`. It is entirely fine to do them `mod
+                // uses e.g., subtraction `mod n`. It is entirely fine to do them `mod
                 // usize::max_value()` instead, because we take the result `mod n` at the end
                 // anyway.
                 inverse = inverse.wrapping_mul(
@@ -2887,12 +2887,12 @@ pub struct NonNull<T: ?Sized> {
 }
 
 /// `NonNull` pointers are not `Send` because the data they reference may be aliased.
-// NB: This impl is unnecessary, but should provide better error messages.
+// N.B., this impl is unnecessary, but should provide better error messages.
 #[stable(feature = "nonnull", since = "1.25.0")]
 impl<T: ?Sized> !Send for NonNull<T> { }
 
 /// `NonNull` pointers are not `Sync` because the data they reference may be aliased.
-// NB: This impl is unnecessary, but should provide better error messages.
+// N.B., this impl is unnecessary, but should provide better error messages.
 #[stable(feature = "nonnull", since = "1.25.0")]
 impl<T: ?Sized> !Sync for NonNull<T> { }
 

src/libcore/raw.rs

@@ -24,7 +24,7 @@
 /// `Box<dyn AnotherTrait>`.
 ///
 /// `TraitObject` is guaranteed to match layouts, but it is not the
-/// type of trait objects (e.g. the fields are not directly accessible
+/// type of trait objects (e.g., the fields are not directly accessible
 /// on a `&SomeTrait`) nor does it control that layout (changing the
 /// definition will not change the layout of a `&SomeTrait`). It is
 /// only designed to be used by unsafe code that needs to manipulate

src/libcore/slice/mod.rs

@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Slice management and manipulation
+//! Slice management and manipulation.
 //!
 //! For more details see [`std::slice`].
 //!
@@ -1151,7 +1151,7 @@ impl<T> [T] {
     ///
     /// # Examples
     ///
-    /// Print the slice split once by numbers divisible by 3 (i.e. `[10, 40]`,
+    /// Print the slice split once by numbers divisible by 3 (i.e., `[10, 40]`,
     /// `[20, 60, 50]`):
     ///
     /// ```
@@ -1215,7 +1215,7 @@ impl<T> [T] {
     /// # Examples
     ///
     /// Print the slice split once, starting from the end, by numbers divisible
-    /// by 3 (i.e. `[50]`, `[10, 40, 30, 20]`):
+    /// by 3 (i.e., `[50]`, `[10, 40, 30, 20]`):
     ///
     /// ```
     /// let v = [10, 40, 30, 20, 60, 50];
@@ -1471,8 +1471,8 @@ impl<T> [T] {
 
     /// Sorts the slice, 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),
+    /// This sort is unstable (i.e., may reorder equal elements), in-place
-    /// and `O(n log n)` worst-case.
+    /// (i.e., does not allocate), and `O(n log n)` worst-case.
     ///
     /// # Current implementation
     ///
@@ -1482,7 +1482,7 @@ impl<T> [T] {
     /// randomization to avoid degenerate cases, but with a fixed seed to always provide
     /// deterministic behavior.
     ///
-    /// It is typically faster than stable sorting, except in a few special cases, e.g. when the
+    /// It is typically faster than stable sorting, except in a few special cases, e.g., when the
     /// slice consists of several concatenated sorted sequences.
     ///
     /// # Examples
@@ -1506,8 +1506,8 @@ impl<T> [T] {
     /// 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),
+    /// This sort is unstable (i.e., may reorder equal elements), in-place
-    /// and `O(n log n)` worst-case.
+    /// (i.e., does not allocate), and `O(n log n)` worst-case.
     ///
     /// 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
@@ -1533,7 +1533,7 @@ impl<T> [T] {
     /// randomization to avoid degenerate cases, but with a fixed seed to always provide
     /// deterministic behavior.
     ///
-    /// It is typically faster than stable sorting, except in a few special cases, e.g. when the
+    /// It is typically faster than stable sorting, except in a few special cases, e.g., when the
     /// slice consists of several concatenated sorted sequences.
     ///
     /// # Examples
@@ -1560,8 +1560,9 @@ impl<T> [T] {
     /// 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),
+    /// This sort is unstable (i.e., may reorder equal elements), in-place
-    /// and `O(m n log(m n))` worst-case, where the key function is `O(m)`.
+    /// (i.e., does not allocate), and `O(m n log(m n))` worst-case, where the key function is
+    /// `O(m)`.
     ///
     /// # Current implementation
     ///
@@ -2458,13 +2459,13 @@ impl<T> SliceIndex<[T]> for usize {
 
     #[inline]
     fn index(self, slice: &[T]) -> &T {
-        // NB: use intrinsic indexing
+        // N.B., use intrinsic indexing
         &(*slice)[self]
     }
 
     #[inline]
     fn index_mut(self, slice: &mut [T]) -> &mut T {
-        // NB: use intrinsic indexing
+        // N.B., use intrinsic indexing
         &mut (*slice)[self]
     }
 }

src/libcore/str/mod.rs

@@ -482,7 +482,7 @@ fn utf8_first_byte(byte: u8, width: u32) -> u32 { (byte & (0x7F >> width)) as u3
 #[inline]
 fn utf8_acc_cont_byte(ch: u32, byte: u8) -> u32 { (ch << 6) | (byte & CONT_MASK) as u32 }
 
-/// Checks whether the byte is a UTF-8 continuation byte (i.e. starts with the
+/// Checks whether the byte is a UTF-8 continuation byte (i.e., starts with the
 /// bits `10`).
 #[inline]
 fn utf8_is_cont_byte(byte: u8) -> bool { (byte & !CONT_MASK) == TAG_CONT_U8 }

src/libcore/str/pattern.rs

@@ -397,7 +397,7 @@ unsafe impl<'a> ReverseSearcher<'a> for CharSearcher<'a> {
                     let found_char = index - shift;
                     if let Some(slice) = haystack.get(found_char..(found_char + self.utf8_size)) {
                         if slice == &self.utf8_encoded[0..self.utf8_size] {
-                            // move finger to before the character found (i.e. at its start index)
+                            // move finger to before the character found (i.e., at its start index)
                             self.finger_back = found_char;
                             return Some((self.finger_back, self.finger_back + self.utf8_size));
                         }
@@ -1016,7 +1016,7 @@ struct TwoWaySearcher {
     It can be proven that the following is an equivalent definition of a local period
     for a factorization (u, v): any positive integer r such that x[i] == x[i+r] for
     all i such that |u| - r <= i <= |u| - 1 and such that both x[i] and x[i+r] are
-    defined. (i.e. i > 0 and i + r < |x|).
+    defined. (i.e., i > 0 and i + r < |x|).
 
     Using the above reformulation, it is easy to prove that
 

src/libcore/task/wake.rs

@@ -227,7 +227,7 @@ pub unsafe trait UnsafeWake: Send + Sync {
     /// # Unsafety
     ///
     /// This function is unsafe to call because it's asserting the `UnsafeWake`
-    /// value is in a consistent state, i.e. hasn't been dropped.
+    /// value is in a consistent state, i.e., hasn't been dropped.
     unsafe fn clone_raw(&self) -> Waker;
 
     /// Drops this instance of `UnsafeWake`, deallocating resources
@@ -249,7 +249,7 @@ pub unsafe trait UnsafeWake: Send + Sync {
     /// # Unsafety
     ///
     /// This function is unsafe to call because it's asserting the `UnsafeWake`
-    /// value is in a consistent state, i.e. hasn't been dropped.
+    /// value is in a consistent state, i.e., hasn't been dropped.
     unsafe fn drop_raw(&self);
 
     /// Indicates that the associated task is ready to make progress and should
@@ -266,7 +266,7 @@ pub unsafe trait UnsafeWake: Send + Sync {
     /// # Unsafety
     ///
     /// This function is unsafe to call because it's asserting the `UnsafeWake`
-    /// value is in a consistent state, i.e. hasn't been dropped.
+    /// value is in a consistent state, i.e., hasn't been dropped.
     unsafe fn wake(&self);
 
     /// Indicates that the associated task is ready to make progress and should
@@ -286,7 +286,7 @@ pub unsafe trait UnsafeWake: Send + Sync {
     /// # Unsafety
     ///
     /// This function is unsafe to call because it's asserting the `UnsafeWake`
-    /// value is in a consistent state, i.e. hasn't been dropped, and that the
+    /// value is in a consistent state, i.e., hasn't been dropped, and that the
     /// `UnsafeWake` hasn't moved from the thread on which it was created.
     unsafe fn wake_local(&self) {
         self.wake()

src/libcore/tests/num/dec2flt/mod.rs

@@ -17,7 +17,7 @@ mod rawfp;
 
 // Take a float literal, turn it into a string in various ways (that are all trusted
 // to be correct) and see if those strings are parsed back to the value of the literal.
-// Requires a *polymorphic literal*, i.e. one that can serve as f64 as well as f32.
+// Requires a *polymorphic literal*, i.e., one that can serve as f64 as well as f32.
 macro_rules! test_literal {
     ($x: expr) => ({
         let x32: f32 = $x;

src/libcore/tests/num/flt2dec/random.rs

@@ -99,7 +99,7 @@ pub fn f32_exhaustive_equivalence_test<F, G>(f: F, g: G, k: usize)
     // this is of course very stressful (and thus should be behind an `#[ignore]` attribute),
     // but with `-C opt-level=3 -C lto` this only takes about an hour or so.
 
-    // iterate from 0x0000_0001 to 0x7f7f_ffff, i.e. all finite ranges
+    // iterate from 0x0000_0001 to 0x7f7f_ffff, i.e., all finite ranges
     let (npassed, nignored) = iterate("f32_exhaustive_equivalence_test",
                                       k, 0x7f7f_ffff, f, g, |i: usize| {
 

src/libcore/time.rs

@@ -216,7 +216,7 @@ impl Duration {
     ///
     /// This method does **not** return the length of the duration when
     /// represented by milliseconds. The returned number always represents a
-    /// fractional portion of a second (i.e. it is less than one thousand).
+    /// fractional portion of a second (i.e., it is less than one thousand).
     ///
     /// # Examples
     ///
@@ -235,7 +235,7 @@ impl Duration {
     ///
     /// This method does **not** return the length of the duration when
     /// represented by microseconds. The returned number always represents a
-    /// fractional portion of a second (i.e. it is less than one million).
+    /// fractional portion of a second (i.e., it is less than one million).
     ///
     /// # Examples
     ///
@@ -254,7 +254,7 @@ impl Duration {
     ///
     /// This method does **not** return the length of the duration when
     /// represented by nanoseconds. The returned number always represents a
-    /// fractional portion of a second (i.e. it is less than one billion).
+    /// fractional portion of a second (i.e., it is less than one billion).
     ///
     /// # Examples
     ///

src/libgraphviz/lib.rs

@@ -10,7 +10,7 @@
 
 //! Generate files suitable for use with [Graphviz](http://www.graphviz.org/)
 //!
-//! The `render` function generates output (e.g. an `output.dot` file) for
+//! The `render` function generates output (e.g., an `output.dot` file) for
 //! use with [Graphviz](http://www.graphviz.org/) by walking a labeled
 //! graph. (Graphviz can then automatically lay out the nodes and edges
 //! of the graph, and also optionally render the graph as an image or
@@ -25,7 +25,7 @@
 //! expressiveness of the [DOT language](
 //! http://www.graphviz.org/doc/info/lang.html). For example, there are
 //! many [attributes](http://www.graphviz.org/content/attrs) related to
-//! providing layout hints (e.g. left-to-right versus top-down, which
+//! providing layout hints (e.g., left-to-right versus top-down, which
 //! algorithm to use, etc). The current intention of this library is to
 //! emit a human-readable .dot file with very regular structure suitable
 //! for easy post-processing.
@@ -373,7 +373,7 @@ impl Style {
 // implement a Labelling service) that I have encountered is that it
 // makes it impossible to use types outside of the current crate
 // directly as Nodes/Edges; you need to wrap them in newtype'd
-// structs. See e.g. the `No` and `Ed` structs in the examples. (In
+// structs. See e.g., the `No` and `Ed` structs in the examples. (In
 // practice clients using a graph in some other crate would need to
 // provide some sort of adapter shim over the graph anyway to
 // interface with this library).
@@ -400,7 +400,7 @@ impl<'a> Id<'a> {
     /// The caller must ensure that the input conforms to an
     /// identifier format: it must be a non-empty string made up of
     /// alphanumeric or underscore characters, not beginning with a
-    /// digit (i.e. the regular expression `[a-zA-Z_][a-zA-Z_0-9]*`).
+    /// digit (i.e., the regular expression `[a-zA-Z_][a-zA-Z_0-9]*`).
     ///
     /// (Note: this format is a strict subset of the `ID` format
     /// defined by the DOT language.  This function may change in the

src/libpanic_unwind/dwarf/mod.rs

@@ -32,7 +32,7 @@ impl DwarfReader {
         DwarfReader { ptr }
     }
 
-    // DWARF streams are packed, so e.g. a u32 would not necessarily be aligned
+    // DWARF streams are packed, so e.g., a u32 would not necessarily be aligned
     // on a 4-byte boundary. This may cause problems on platforms with strict
     // alignment requirements. By wrapping data in a "packed" struct, we are
     // telling the backend to generate "misalignment-safe" code.

src/libpanic_unwind/gcc.rs

@@ -25,7 +25,7 @@
 //!
 //! In both phases the unwinder walks stack frames from top to bottom using
 //! information from the stack frame unwind sections of the current process's
-//! modules ("module" here refers to an OS module, i.e. an executable or a
+//! modules ("module" here refers to an OS module, i.e., an executable or a
 //! dynamic library).
 //!
 //! For each stack frame, it invokes the associated "personality routine", whose
@@ -296,7 +296,7 @@ unsafe extern "C" fn rust_eh_unwind_resume(panic_ctx: *mut u8) -> ! {
 // Each module's image contains a frame unwind info section (usually
 // ".eh_frame").  When a module is loaded/unloaded into the process, the
 // unwinder must be informed about the location of this section in memory. The
-// methods of achieving that vary by the platform.  On some (e.g. Linux), the
+// methods of achieving that vary by the platform.  On some (e.g., Linux), the
 // unwinder can discover unwind info sections on its own (by dynamically
 // enumerating currently loaded modules via the dl_iterate_phdr() API and
 // finding their ".eh_frame" sections); Others, like Windows, require modules

src/libpanic_unwind/seh.rs

@@ -12,7 +12,7 @@
 //!
 //! On Windows (currently only on MSVC), the default exception handling
 //! mechanism is Structured Exception Handling (SEH). This is quite different
-//! than Dwarf-based exception handling (e.g. what other unix platforms use) in
+//! than Dwarf-based exception handling (e.g., what other unix platforms use) in
 //! terms of compiler internals, so LLVM is required to have a good deal of
 //! extra support for SEH.
 //!
@@ -304,7 +304,7 @@ pub unsafe fn cleanup(payload: [u64; 2]) -> Box<dyn Any + Send> {
     })
 }
 
-// This is required by the compiler to exist (e.g. it's a lang item), but
+// This is required by the compiler to exist (e.g., it's a lang item), but
 // it's never actually called by the compiler because __C_specific_handler
 // or _except_handler3 is the personality function that is always used.
 // Hence this is just an aborting stub.

src/libproc_macro/bridge/client.rs

@@ -262,7 +262,7 @@ enum BridgeState<'a> {
     Connected(Bridge<'a>),
 
     /// Access to the bridge is being exclusively acquired
-    /// (e.g. during `BridgeState::with`).
+    /// (e.g., during `BridgeState::with`).
     InUse,
 }
 
@@ -283,7 +283,7 @@ impl BridgeState<'_> {
     /// The state will be restored after `f` exits, even
     /// by panic, including modifications made to it by `f`.
     ///
-    /// NB: while `f` is running, the thread-local state
+    /// N.B., while `f` is running, the thread-local state
     /// is `BridgeState::InUse`.
     fn with<R>(f: impl FnOnce(&mut BridgeState) -> R) -> R {
         BRIDGE_STATE.with(|state| {
@@ -333,7 +333,7 @@ impl Bridge<'_> {
 /// which may be using a different `proc_macro` from the one
 /// used by the server, but can be interacted with compatibly.
 ///
-/// NB: `F` must have FFI-friendly memory layout (e.g. a pointer).
+/// N.B., `F` must have FFI-friendly memory layout (e.g., a pointer).
 /// The call ABI of function pointers used for `F` doesn't
 /// need to match between server and client, since it's only
 /// passed between them and (eventually) called by the client.

src/libproc_macro/bridge/mod.rs

@@ -14,7 +14,7 @@
 //! Serialization (with C ABI buffers) and unique integer handles are employed
 //! to allow safely interfacing between two copies of `proc_macro` built
 //! (from the same source) by different compilers with potentially mismatching
-//! Rust ABIs (e.g. stage0/bin/rustc vs stage1/bin/rustc during bootstrap).
+//! Rust ABIs (e.g., stage0/bin/rustc vs stage1/bin/rustc during bootstrap).
 
 #![deny(unsafe_code)]
 

src/libproc_macro/bridge/scoped_cell.rs

@@ -19,7 +19,7 @@ pub trait ApplyL<'a> {
     type Out;
 }
 
-/// Type lambda taking a lifetime, i.e. `Lifetime -> Type`.
+/// Type lambda taking a lifetime, i.e., `Lifetime -> Type`.
 pub trait LambdaL: for<'a> ApplyL<'a> {}
 
 impl<T: for<'a> ApplyL<'a>> LambdaL for T {}

src/libproc_macro/bridge/server.rs

@@ -16,7 +16,7 @@ use super::*;
 use super::client::HandleStore;
 
 /// Declare an associated item of one of the traits below, optionally
-/// adjusting it (i.e. adding bounds to types and default bodies to methods).
+/// adjusting it (i.e., adding bounds to types and default bodies to methods).
 macro_rules! associated_item {
     (type TokenStream) =>
         (type TokenStream: 'static + Clone;);

src/libproc_macro/lib.rs

@@ -110,7 +110,7 @@ impl FromStr for TokenStream {
     }
 }
 
-// NB: the bridge only provides `to_string`, implement `fmt::Display`
+// N.B., the bridge only provides `to_string`, implement `fmt::Display`
 // based on it (the reverse of the usual relationship between the two).
 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
 impl ToString for TokenStream {
@@ -196,7 +196,7 @@ pub mod token_stream {
     use {bridge, Group, Ident, Literal, Punct, TokenTree, TokenStream};
 
     /// An iterator over `TokenStream`'s `TokenTree`s.
-    /// The iteration is "shallow", e.g. the iterator doesn't recurse into delimited groups,
+    /// The iteration is "shallow", e.g., the iterator doesn't recurse into delimited groups,
     /// and returns whole groups as token trees.
     #[derive(Clone)]
     #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
@@ -426,7 +426,7 @@ impl PartialEq for SourceFile {
 #[unstable(feature = "proc_macro_span", issue = "54725")]
 impl Eq for SourceFile {}
 
-/// A single token or a delimited sequence of token trees (e.g. `[1, (), ..]`).
+/// A single token or a delimited sequence of token trees (e.g., `[1, (), ..]`).
 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
 #[derive(Clone)]
 pub enum TokenTree {
@@ -533,7 +533,7 @@ impl From<Literal> for TokenTree {
     }
 }
 
-// NB: the bridge only provides `to_string`, implement `fmt::Display`
+// N.B., the bridge only provides `to_string`, implement `fmt::Display`
 // based on it (the reverse of the usual relationship between the two).
 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
 impl ToString for TokenTree {
@@ -663,7 +663,7 @@ impl Group {
     }
 }
 
-// NB: the bridge only provides `to_string`, implement `fmt::Display`
+// N.B., the bridge only provides `to_string`, implement `fmt::Display`
 // based on it (the reverse of the usual relationship between the two).
 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
 impl ToString for Group {
@@ -711,10 +711,10 @@ impl !Sync for Punct {}
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
 pub enum Spacing {
-    /// E.g. `+` is `Alone` in `+ =`, `+ident` or `+()`.
+    /// e.g., `+` is `Alone` in `+ =`, `+ident` or `+()`.
     #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
     Alone,
-    /// E.g. `+` is `Joint` in `+=` or `'#`.
+    /// e.g., `+` is `Joint` in `+=` or `'#`.
     /// Additionally, single quote `'` can join with identifiers to form lifetimes `'ident`.
     #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
     Joint,
@@ -765,7 +765,7 @@ impl Punct {
     }
 }
 
-// NB: the bridge only provides `to_string`, implement `fmt::Display`
+// N.B., the bridge only provides `to_string`, implement `fmt::Display`
 // based on it (the reverse of the usual relationship between the two).
 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
 impl ToString for Punct {
@@ -860,7 +860,7 @@ impl Ident {
     }
 }
 
-// NB: the bridge only provides `to_string`, implement `fmt::Display`
+// N.B., the bridge only provides `to_string`, implement `fmt::Display`
 // based on it (the reverse of the usual relationship between the two).
 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
 impl ToString for Ident {
@@ -1110,7 +1110,7 @@ impl Literal {
     }
 }
 
-// NB: the bridge only provides `to_string`, implement `fmt::Display`
+// N.B., the bridge only provides `to_string`, implement `fmt::Display`
 // based on it (the reverse of the usual relationship between the two).
 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
 impl ToString for Literal {

src/librustc/cfg/construct.rs

@@ -379,7 +379,7 @@ impl<'a, 'tcx> CFGBuilder<'a, 'tcx> {
             }
 
             hir::ExprKind::Index(ref l, ref r) |
-            hir::ExprKind::Binary(_, ref l, ref r) => { // NB: && and || handled earlier
+            hir::ExprKind::Binary(_, ref l, ref r) => { // N.B., && and || handled earlier
                 self.straightline(expr, pred, [l, r].iter().map(|&e| &**e))
             }
 

src/librustc/dep_graph/dep_node.rs

@@ -17,7 +17,7 @@
 //! fully identify a dependency node, even across multiple compilation sessions.
 //! In other words, the value of the fingerprint does not depend on anything
 //! that is specific to a given compilation session, like an unpredictable
-//! interning key (e.g. NodeId, DefId, Symbol) or the numeric value of a
+//! interning key (e.g., NodeId, DefId, Symbol) or the numeric value of a
 //! pointer. The concept behind this could be compared to how git commit hashes
 //! uniquely identify a given commit and has a few advantages:
 //!
@@ -28,7 +28,7 @@
 //! * A `Fingerprint` is just a bunch of bits, which allows `DepNode` to
 //!   implement `Copy`, `Sync`, `Send`, `Freeze`, etc.
 //! * Since we just have a bit pattern, `DepNode` can be mapped from disk into
-//!   memory without any post-processing (e.g. "abomination-style" pointer
+//!   memory without any post-processing (e.g., "abomination-style" pointer
 //!   reconstruction).
 //! * Because a `DepNode` is self-contained, we can instantiate `DepNodes` that
 //!   refer to things that do not exist anymore. In previous implementations
@@ -81,7 +81,7 @@ use ty::{TyCtxt, FnSig, Instance, InstanceDef,
 use ty::subst::Substs;
 
 // erase!() just makes tokens go away. It's used to specify which macro argument
-// is repeated (i.e. which sub-expression of the macro we are in) but don't need
+// is repeated (i.e., which sub-expression of the macro we are in) but don't need
 // to actually use any of the arguments.
 macro_rules! erase {
     ($x:tt) => ({})

src/librustc/diagnostics.rs

@@ -47,7 +47,7 @@ trait Foo where Self: Sized {
 We cannot create an object of type `Box<Foo>` or `&Foo` since in this case
 `Self` would not be `Sized`.
 
-Generally, `Self : Sized` is used to indicate that the trait should not be used
+Generally, `Self: Sized` is used to indicate that the trait should not be used
 as a trait object. If the trait comes from your own crate, consider removing
 this restriction.
 
@@ -217,9 +217,9 @@ trait Trait {
 ```
 
 If this is not an option, consider replacing the type parameter with another
-trait object (e.g. if `T: OtherTrait`, use `on: Box<OtherTrait>`). If the number
+trait object (e.g., if `T: OtherTrait`, use `on: Box<OtherTrait>`). If the
-of types you intend to feed to this method is limited, consider manually listing
+number of types you intend to feed to this method is limited, consider manually
-out the methods of different types.
+listing out the methods of different types.
 
 ### Method has no receiver
 
@@ -642,7 +642,7 @@ struct Foo; // error: duplicate lang item found: `arc`
 ```
 
 Lang items are already implemented in the standard library. Unless you are
-writing a free-standing application (e.g. a kernel), you do not need to provide
+writing a free-standing application (e.g., a kernel), you do not need to provide
 them yourself.
 
 You can build a free-standing crate by adding `#![no_std]` to the crate
@@ -699,7 +699,7 @@ This error appears when the curly braces contain an identifier which doesn't
 match with any of the type parameters or the string `Self`. This might happen
 if you misspelled a type parameter, or if you intended to use literal curly
 braces. If it is the latter, escape the curly braces with a second curly brace
-of the same type; e.g. a literal `{` is `{{`.
+of the same type; e.g., a literal `{` is `{{`.
 "##,
 
 E0231: r##"
@@ -832,7 +832,7 @@ extern "C" {
 
 E0271: r##"
 This is because of a type mismatch between the associated type of some
-trait (e.g. `T::Bar`, where `T` implements `trait Quux { type Bar; }`)
+trait (e.g., `T::Bar`, where `T` implements `trait Quux { type Bar; }`)
 and another type `U` that is required to be equal to `T::Bar`, but is not.
 Examples follow.
 
@@ -1622,7 +1622,7 @@ representation of enums isn't strictly defined in Rust, and this attribute
 won't work on enums.
 
 `#[repr(simd)]` will give a struct consisting of a homogeneous series of machine
-types (i.e. `u8`, `i32`, etc) a representation that permits vectorization via
+types (i.e., `u8`, `i32`, etc) a representation that permits vectorization via
 SIMD. This doesn't make much sense for enums since they don't consist of a
 single list of data.
 "##,

src/librustc/hir/def.rs

@@ -46,7 +46,7 @@ pub enum NonMacroAttrKind {
 pub enum Def {
     // Type namespace
     Mod(DefId),
-    Struct(DefId), // DefId refers to NodeId of the struct itself
+    Struct(DefId), // `DefId` refers to `NodeId` of the struct itself
     Union(DefId),
     Enum(DefId),
     Variant(DefId),
@@ -63,27 +63,27 @@ pub enum Def {
     PrimTy(hir::PrimTy),
     TyParam(DefId),
     SelfTy(Option<DefId> /* trait */, Option<DefId> /* impl */),
-    ToolMod, // e.g. `rustfmt` in `#[rustfmt::skip]`
+    ToolMod, // e.g., `rustfmt` in `#[rustfmt::skip]`
 
     // Value namespace
     Fn(DefId),
     Const(DefId),
     Static(DefId, bool /* is_mutbl */),
-    StructCtor(DefId, CtorKind), // DefId refers to NodeId of the struct's constructor
+    StructCtor(DefId, CtorKind), // `DefId` refers to `NodeId` of the struct's constructor
-    VariantCtor(DefId, CtorKind), // DefId refers to the enum variant
+    VariantCtor(DefId, CtorKind), // `DefId` refers to the enum variant
-    SelfCtor(DefId /* impl */),  // DefId refers to the impl
+    SelfCtor(DefId /* impl */),  // `DefId` refers to the impl
     Method(DefId),
     AssociatedConst(DefId),
 
     Local(ast::NodeId),
-    Upvar(ast::NodeId,  // node id of closed over local
+    Upvar(ast::NodeId,  // `NodeId` of closed over local
-          usize,        // index in the freevars list of the closure
+          usize,        // index in the `freevars` list of the closure
           ast::NodeId), // expr node that creates the closure
     Label(ast::NodeId),
 
     // Macro namespace
     Macro(DefId, MacroKind),
-    NonMacroAttr(NonMacroAttrKind), // e.g. `#[inline]` or `#[rustfmt::skip]`
+    NonMacroAttr(NonMacroAttrKind), // e.g., `#[inline]` or `#[rustfmt::skip]`
 
     // Both namespaces
     Err,
@@ -170,6 +170,7 @@ impl<T> PerNS<T> {
 
 impl<T> ::std::ops::Index<Namespace> for PerNS<T> {
     type Output = T;
+
     fn index(&self, ns: Namespace) -> &T {
         match ns {
             ValueNS => &self.value_ns,
@@ -238,6 +239,7 @@ impl CtorKind {
             ast::VariantData::Struct(..) => CtorKind::Fictive,
         }
     }
+
     pub fn from_hir(vdata: &hir::VariantData) -> CtorKind {
         match *vdata {
             hir::VariantData::Tuple(..) => CtorKind::Fn,

src/librustc/hir/intravisit.rs

@@ -131,7 +131,7 @@ impl<'this, 'tcx> NestedVisitorMap<'this, 'tcx> {
 /// Each method of the Visitor trait is a hook to be potentially
 /// overridden.  Each method's default implementation recursively visits
 /// the substructure of the input via the corresponding `walk` method;
-/// e.g. the `visit_mod` method by default calls `intravisit::walk_mod`.
+/// e.g., the `visit_mod` method by default calls `intravisit::walk_mod`.
 ///
 /// Note that this visitor does NOT visit nested items by default
 /// (this is why the module is called `intravisit`, to distinguish it
@@ -493,7 +493,7 @@ pub fn walk_item<'v, V: Visitor<'v>>(visitor: &mut V, item: &'v Item) {
                              item.id)
         }
         ItemKind::Mod(ref module) => {
-            // visit_mod() takes care of visiting the Item's NodeId
+            // `visit_mod()` takes care of visiting the `Item`'s `NodeId`.
             visitor.visit_mod(module, item.span, item.id)
         }
         ItemKind::ForeignMod(ref foreign_module) => {
@@ -518,7 +518,7 @@ pub fn walk_item<'v, V: Visitor<'v>>(visitor: &mut V, item: &'v Item) {
         }
         ItemKind::Enum(ref enum_definition, ref type_parameters) => {
             visitor.visit_generics(type_parameters);
-            // visit_enum_def() takes care of visiting the Item's NodeId
+            // `visit_enum_def()` takes care of visiting the `Item`'s `NodeId`.
             visitor.visit_enum_def(enum_definition, type_parameters, item.id, item.span)
         }
         ItemKind::Impl(
@@ -877,7 +877,7 @@ pub fn walk_trait_item<'v, V: Visitor<'v>>(visitor: &mut V, trait_item: &'v Trai
 }
 
 pub fn walk_trait_item_ref<'v, V: Visitor<'v>>(visitor: &mut V, trait_item_ref: &'v TraitItemRef) {
-    // NB: Deliberately force a compilation error if/when new fields are added.
+    // N.B., deliberately force a compilation error if/when new fields are added.
     let TraitItemRef { id, ident, ref kind, span: _, ref defaultness } = *trait_item_ref;
     visitor.visit_nested_trait_item(id);
     visitor.visit_ident(ident);
@@ -886,7 +886,7 @@ pub fn walk_trait_item_ref<'v, V: Visitor<'v>>(visitor: &mut V, trait_item_ref:
 }
 
 pub fn walk_impl_item<'v, V: Visitor<'v>>(visitor: &mut V, impl_item: &'v ImplItem) {
-    // NB: Deliberately force a compilation error if/when new fields are added.
+    // N.B., deliberately force a compilation error if/when new fields are added.
     let ImplItem {
         id: _,
         hir_id: _,
@@ -932,7 +932,7 @@ pub fn walk_impl_item<'v, V: Visitor<'v>>(visitor: &mut V, impl_item: &'v ImplIt
 }
 
 pub fn walk_impl_item_ref<'v, V: Visitor<'v>>(visitor: &mut V, impl_item_ref: &'v ImplItemRef) {
-    // NB: Deliberately force a compilation error if/when new fields are added.
+    // N.B., deliberately force a compilation error if/when new fields are added.
     let ImplItemRef { id, ident, ref kind, span: _, ref vis, ref defaultness } = *impl_item_ref;
     visitor.visit_nested_impl_item(id);
     visitor.visit_ident(ident);

src/librustc/hir/lowering.rs

@@ -82,7 +82,7 @@ const HIR_ID_COUNTER_LOCKED: u32 = 0xFFFFFFFF;
 pub struct LoweringContext<'a> {
     crate_root: Option<&'static str>,
 
-    // Use to assign ids to hir nodes that do not directly correspond to an ast node
+    // Used to assign ids to HIR nodes that do not directly correspond to an AST node.
     sess: &'a Session,
 
     cstore: &'a dyn CrateStore,
@@ -114,10 +114,10 @@ pub struct LoweringContext<'a> {
     anonymous_lifetime_mode: AnonymousLifetimeMode,
 
     // Used to create lifetime definitions from in-band lifetime usages.
-    // e.g. `fn foo(x: &'x u8) -> &'x u8` to `fn foo<'x>(x: &'x u8) -> &'x u8`
+    // e.g., `fn foo(x: &'x u8) -> &'x u8` to `fn foo<'x>(x: &'x u8) -> &'x u8`
     // When a named lifetime is encountered in a function or impl header and
     // has not been defined
-    // (i.e. it doesn't appear in the in_scope_lifetimes list), it is added
+    // (i.e., it doesn't appear in the in_scope_lifetimes list), it is added
     // to this list. The results of this list are then added to the list of
     // lifetime definitions in the corresponding impl or function generics.
     lifetimes_to_define: Vec<(Span, ParamName)>,
@@ -149,7 +149,7 @@ pub trait Resolver {
         is_value: bool,
     ) -> hir::Path;
 
-    /// Obtain the resolution for a node id
+    /// Obtain the resolution for a node-id.
     fn get_resolution(&mut self, id: NodeId) -> Option<PathResolution>;
 
     /// Obtain the possible resolutions for the given `use` statement.
@@ -159,8 +159,8 @@ pub trait Resolver {
     /// This should only return `None` during testing.
     fn definitions(&mut self) -> &mut Definitions;
 
-    /// Given suffix ["b","c","d"], creates a HIR path for `[::crate_root]::b::c::d` and resolves
+    /// Given suffix `["b", "c", "d"]`, creates a HIR path for `[::crate_root]::b::c::d` and
-    /// it based on `is_value`.
+    /// resolves it based on `is_value`.
     fn resolve_str_path(
         &mut self,
         span: Span,
@@ -185,7 +185,7 @@ enum ImplTraitContext<'a> {
     ///
     /// We optionally store a `DefId` for the parent item here so we can look up necessary
     /// information later. It is `None` when no information about the context should be stored,
-    /// e.g. for consts and statics.
+    /// e.g., for consts and statics.
     Existential(Option<DefId>),
 
     /// `impl Trait` is not accepted in this position.
@@ -358,8 +358,8 @@ impl<'a> LoweringContext<'a> {
     fn lower_crate(mut self, c: &Crate) -> hir::Crate {
         /// Full-crate AST visitor that inserts into a fresh
         /// `LoweringContext` any information that may be
-        /// needed from arbitrary locations in the crate.
+        /// needed from arbitrary locations in the crate,
-        /// E.g. The number of lifetime generic parameters
+        /// e.g., the number of lifetime generic parameters
         /// declared for every type and trait definition.
         struct MiscCollector<'lcx, 'interner: 'lcx> {
             lctx: &'lcx mut LoweringContext<'interner>,
@@ -512,7 +512,7 @@ impl<'a> LoweringContext<'a> {
                 debug
             );
         }
-        // Always allocate the first HirId for the owner itself
+        // Always allocate the first `HirId` for the owner itself.
         self.lower_node_id_with_owner(owner, owner)
     }
 
@@ -536,7 +536,7 @@ impl<'a> LoweringContext<'a> {
         let existing_hir_id = self.node_id_to_hir_id[ast_node_id];
 
         if existing_hir_id == hir::DUMMY_HIR_ID {
-            // Generate a new HirId
+            // Generate a new `HirId`.
             let hir_id = alloc_hir_id(self);
             self.node_id_to_hir_id[ast_node_id] = hir_id;
             LoweredNodeId {
@@ -573,12 +573,12 @@ impl<'a> LoweringContext<'a> {
         ret
     }
 
-    /// This method allocates a new HirId for the given NodeId and stores it in
+    /// This method allocates a new `HirId` for the given `NodeId` and stores it in
-    /// the LoweringContext's NodeId => HirId map.
+    /// the `LoweringContext`'s `NodeId => HirId` map.
-    /// Take care not to call this method if the resulting HirId is then not
+    /// Take care not to call this method if the resulting `HirId` is then not
     /// actually used in the HIR, as that would trigger an assertion in the
-    /// HirIdValidator later on, which makes sure that all NodeIds got mapped
+    /// `HirIdValidator` later on, which makes sure that all `NodeId`s got mapped
-    /// properly. Calling the method twice with the same NodeId is fine though.
+    /// properly. Calling the method twice with the same `NodeId` is fine though.
     fn lower_node_id(&mut self, ast_node_id: NodeId) -> LoweredNodeId {
         self.lower_node_id_generic(ast_node_id, |this| {
             let &mut (def_index, ref mut local_id_counter) =
@@ -743,7 +743,7 @@ impl<'a> LoweringContext<'a> {
                     ),
                 };
 
-                // Add a definition for the in-band lifetime def
+                // Add a definition for the in-band lifetime def.
                 self.resolver.definitions().create_def_with_parent(
                     parent_id.index,
                     def_node_id,
@@ -1067,7 +1067,7 @@ impl<'a> LoweringContext<'a> {
     fn lower_attr(&mut self, attr: &Attribute) -> Attribute {
         // Note that we explicitly do not walk the path. Since we don't really
         // lower attributes (we use the AST version) there is nowhere to keep
-        // the HirIds. We don't actually need HIR version of attributes anyway.
+        // the `HirId`s. We don't actually need HIR version of attributes anyway.
         Attribute {
             id: attr.id,
             style: attr.style,
@@ -1246,7 +1246,7 @@ impl<'a> LoweringContext<'a> {
                     }
                     ImplTraitContext::Universal(in_band_ty_params) => {
                         self.lower_node_id(def_node_id);
-                        // Add a definition for the in-band Param
+                        // Add a definition for the in-band `Param`.
                         let def_index = self
                             .resolver
                             .definitions()
@@ -1257,7 +1257,7 @@ impl<'a> LoweringContext<'a> {
                             bounds,
                             ImplTraitContext::Universal(in_band_ty_params),
                         );
-                        // Set the name to `impl Bound1 + Bound2`
+                        // Set the name to `impl Bound1 + Bound2`.
                         let ident = Ident::from_str(&pprust::ty_to_string(t)).with_span_pos(span);
                         in_band_ty_params.push(hir::GenericParam {
                             id: def_node_id,
@@ -1365,7 +1365,7 @@ impl<'a> LoweringContext<'a> {
                 impl_trait_fn: fn_def_id,
             });
             let exist_ty_id = lctx.lower_node_id(exist_ty_node_id);
-            // Generate an `existential type Foo: Trait;` declaration
+            // Generate an `existential type Foo: Trait;` declaration.
             trace!("creating existential type with id {:#?}", exist_ty_id);
 
             trace!("exist ty def index: {:#?}", exist_ty_def_index);
@@ -1384,7 +1384,7 @@ impl<'a> LoweringContext<'a> {
             // does not actually exist in the AST.
             lctx.items.insert(exist_ty_id.node_id, exist_ty_item);
 
-            // `impl Trait` now just becomes `Foo<'a, 'b, ..>`
+            // `impl Trait` now just becomes `Foo<'a, 'b, ..>`.
             hir::TyKind::Def(hir::ItemId { id: exist_ty_id.node_id }, lifetimes)
         })
     }
@@ -1397,7 +1397,7 @@ impl<'a> LoweringContext<'a> {
     ) -> (HirVec<hir::GenericArg>, HirVec<hir::GenericParam>) {
         // This visitor walks over impl trait bounds and creates defs for all lifetimes which
         // appear in the bounds, excluding lifetimes that are created within the bounds.
-        // e.g. 'a, 'b, but not 'c in `impl for<'c> SomeTrait<'a, 'b, 'c>`
+        // E.g., `'a`, `'b`, but not `'c` in `impl for<'c> SomeTrait<'a, 'b, 'c>`.
         struct ImplTraitLifetimeCollector<'r, 'a: 'r> {
             context: &'r mut LoweringContext<'a>,
             parent: DefIndex,
@@ -1429,7 +1429,7 @@ impl<'a> LoweringContext<'a> {
             }
 
             fn visit_ty(&mut self, t: &'v hir::Ty) {
-                // Don't collect elided lifetimes used inside of `fn()` syntax
+                // Don't collect elided lifetimes used inside of `fn()` syntax.
                 if let hir::TyKind::BareFn(_) = t.node {
                     let old_collect_elided_lifetimes = self.collect_elided_lifetimes;
                     self.collect_elided_lifetimes = false;
@@ -1459,10 +1459,10 @@ impl<'a> LoweringContext<'a> {
             }
 
             fn visit_generic_param(&mut self, param: &'v hir::GenericParam) {
-                // Record the introduction of 'a in `for<'a> ...`
+                // Record the introduction of 'a in `for<'a> ...`.
                 if let hir::GenericParamKind::Lifetime { .. } = param.kind {
                     // Introduce lifetimes one at a time so that we can handle
-                    // cases like `fn foo<'d>() -> impl for<'a, 'b: 'a, 'c: 'b + 'd>`
+                    // cases like `fn foo<'d>() -> impl for<'a, 'b: 'a, 'c: 'b + 'd>`.
                     let lt_name = hir::LifetimeName::Param(param.name);
                     self.currently_bound_lifetimes.push(lt_name);
                 }
@@ -1475,7 +1475,7 @@ impl<'a> LoweringContext<'a> {
                     hir::LifetimeName::Implicit | hir::LifetimeName::Underscore => {
                         if self.collect_elided_lifetimes {
                             // Use `'_` for both implicit and underscore lifetimes in
-                            // `abstract type Foo<'_>: SomeTrait<'_>;`
+                            // `abstract type Foo<'_>: SomeTrait<'_>;`.
                             hir::LifetimeName::Underscore
                         } else {
                             return;
@@ -1648,7 +1648,7 @@ impl<'a> LoweringContext<'a> {
                         {
                             ParenthesizedGenericArgs::Ok
                         }
-                        // Avoid duplicated errors
+                        // Avoid duplicated errors.
                         Def::Err => ParenthesizedGenericArgs::Ok,
                         // An error
                         Def::Struct(..)
@@ -1689,7 +1689,7 @@ impl<'a> LoweringContext<'a> {
         });
 
         // Simple case, either no projections, or only fully-qualified.
-        // E.g. `std::mem::size_of` or `<I as Iterator>::Item`.
+        // E.g., `std::mem::size_of` or `<I as Iterator>::Item`.
         if resolution.unresolved_segments() == 0 {
             return hir::QPath::Resolved(qself, path);
         }
@@ -1697,11 +1697,11 @@ impl<'a> LoweringContext<'a> {
         // Create the innermost type that we're projecting from.
         let mut ty = if path.segments.is_empty() {
             // If the base path is empty that means there exists a
-            // syntactical `Self`, e.g. `&i32` in `<&i32>::clone`.
+            // syntactical `Self`, e.g., `&i32` in `<&i32>::clone`.
             qself.expect("missing QSelf for <T>::...")
         } else {
             // Otherwise, the base path is an implicit `Self` type path,
-            // e.g. `Vec` in `Vec::new` or `<I as Iterator>::Item` in
+            // e.g., `Vec` in `Vec::new` or `<I as Iterator>::Item` in
             // `<I as Iterator>::Item::default`.
             let new_id = self.next_id();
             P(self.ty_path(new_id, p.span, hir::QPath::Resolved(qself, path)))
@@ -1709,7 +1709,7 @@ impl<'a> LoweringContext<'a> {
 
         // Anything after the base path are associated "extensions",
         // out of which all but the last one are associated types,
-        // e.g. for `std::vec::Vec::<T>::IntoIter::Item::clone`:
+        // e.g., for `std::vec::Vec::<T>::IntoIter::Item::clone`:
         // * base path is `std::vec::Vec<T>`
         // * "extensions" are `IntoIter`, `Item` and `clone`
         // * type nodes are:
@@ -1739,7 +1739,7 @@ impl<'a> LoweringContext<'a> {
             ty = P(self.ty_path(new_id, p.span, qpath));
         }
 
-        // Should've returned in the for loop above.
+        // We should've returned in the for loop above.
         span_bug!(
             p.span,
             "lower_qpath: no final extension segment in {}..{}",
@@ -1838,11 +1838,11 @@ impl<'a> LoweringContext<'a> {
                 let no_bindings = generic_args.bindings.is_empty();
                 let (incl_angl_brckt, insertion_span, suggestion) = if no_ty_args && no_bindings {
                     // If there are no (non-implicit) generic args or associated-type
-                    // bindings, our suggestion includes the angle brackets
+                    // bindings, our suggestion includes the angle brackets.
                     (true, path_span.shrink_to_hi(), format!("<{}>", anon_lt_suggestion))
                 } else {
                     // Otherwise—sorry, this is kind of gross—we need to infer the
-                    // place to splice in the `'_, ` from the generics that do exist
+                    // place to splice in the `'_, ` from the generics that do exist.
                     let first_generic_span = first_generic_span
                         .expect("already checked that type args or bindings exist");
                     (false, first_generic_span.shrink_to_lo(), format!("{}, ", anon_lt_suggestion))
@@ -2096,14 +2096,15 @@ impl<'a> LoweringContext<'a> {
         return_impl_trait_id: NodeId,
     ) -> hir::FunctionRetTy {
         // Get lifetimes used in the input arguments to the function. Our output type must also
-        // have the same lifetime. FIXME(cramertj) multiple different lifetimes are not allowed
+        // have the same lifetime.
-        // because `impl Trait + 'a + 'b` doesn't allow for capture `'a` and `'b` where neither
+        // FIXME(cramertj): multiple different lifetimes are not allowed because
-        // is a subset of the other. We really want some new lifetime that is a subset of all input
+        // `impl Trait + 'a + 'b` doesn't allow for capture `'a` and `'b` where neither is a subset
-        // lifetimes, but that doesn't exist at the moment.
+        // of the other. We really want some new lifetime that is a subset of all input lifetimes,
+        // but that doesn't exist at the moment.
 
         struct AsyncFnLifetimeCollector<'r, 'a: 'r> {
             context: &'r mut LoweringContext<'a>,
-            // Lifetimes bound by HRTB
+            // Lifetimes bound by HRTB.
             currently_bound_lifetimes: Vec<hir::LifetimeName>,
             // Whether to count elided lifetimes.
             // Disabled inside of `Fn` or `fn` syntax.
@@ -2133,7 +2134,7 @@ impl<'a> LoweringContext<'a> {
             }
 
             fn visit_ty(&mut self, t: &'v hir::Ty) {
-                // Don't collect elided lifetimes used inside of `fn()` syntax
+                // Don't collect elided lifetimes used inside of `fn()` syntax.
                 if let &hir::TyKind::BareFn(_) = &t.node {
                     let old_collect_elided_lifetimes = self.collect_elided_lifetimes;
                     self.collect_elided_lifetimes = false;
@@ -2424,7 +2425,7 @@ impl<'a> LoweringContext<'a> {
             GenericParamKind::Type { ref default, .. } => {
                 // Don't expose `Self` (recovered "keyword used as ident" parse error).
                 // `rustc::ty` expects `Self` to be only used for a trait's `Self`.
-                // Instead, use gensym("Self") to create a distinct name that looks the same.
+                // Instead, use `gensym("Self")` to create a distinct name that looks the same.
                 let ident = if param.ident.name == keywords::SelfUpper.name() {
                     param.ident.gensym()
                 } else {
@@ -2467,7 +2468,7 @@ impl<'a> LoweringContext<'a> {
         -> hir::Generics
     {
         // Collect `?Trait` bounds in where clause and move them to parameter definitions.
-        // FIXME: This could probably be done with less rightward drift. Also looks like two control
+        // FIXME: this could probably be done with less rightward drift. Also looks like two control
         //        paths where report_error is called are also the only paths that advance to after
         //        the match statement, so the error reporting could probably just be moved there.
         let mut add_bounds: NodeMap<Vec<_>> = Default::default();
@@ -2563,7 +2564,7 @@ impl<'a> LoweringContext<'a> {
                                 .iter()
                                 .filter_map(|bound| match *bound {
                                     // Ignore `?Trait` bounds.
-                                    // Tthey were copied into type parameters already.
+                                    // They were copied into type parameters already.
                                     GenericBound::Trait(_, TraitBoundModifier::Maybe) => None,
                                     _ => Some(this.lower_param_bound(
                                         bound,
@@ -2662,7 +2663,7 @@ impl<'a> LoweringContext<'a> {
             id: self.lower_node_id(f.id).node_id,
             ident: match f.ident {
                 Some(ident) => ident,
-                // FIXME(jseyfried) positional field hygiene
+                // FIXME(jseyfried): positional field hygiene
                 None => Ident::new(Symbol::intern(&index.to_string()), f.span),
             },
             vis: self.lower_visibility(&f.vis, None),
@@ -2946,7 +2947,7 @@ impl<'a> LoweringContext<'a> {
         }
 
         // [1] `defaultness.has_value()` is never called for an `impl`, always `true` in order to
-        //     not cause an assertion failure inside the `lower_defaultness` function
+        //     not cause an assertion failure inside the `lower_defaultness` function.
     }
 
     fn lower_use_tree(
@@ -3190,7 +3191,7 @@ impl<'a> LoweringContext<'a> {
 
     /// Paths like the visibility path in `pub(super) use foo::{bar, baz}` are repeated
     /// many times in the HIR tree; for each occurrence, we need to assign distinct
-    /// node-ids. (See e.g. #56128.)
+    /// node-ids. (See e.g., #56128.)
     fn renumber_segment_ids(&mut self, path: &P<hir::Path>) -> P<hir::Path> {
         debug!("renumber_segment_ids(path = {:?})", path);
         let mut path = path.clone();
@@ -3780,7 +3781,7 @@ impl<'a> LoweringContext<'a> {
                 let else_opt = else_opt.as_ref().map(|els| {
                     match els.node {
                         ExprKind::IfLet(..) => {
-                            // wrap the if-let expr in a block
+                            // Wrap the `if let` expr in a block.
                             let span = els.span;
                             let els = P(self.lower_expr(els));
                             let LoweredNodeId { node_id, hir_id } = self.next_id();
@@ -3871,7 +3872,7 @@ impl<'a> LoweringContext<'a> {
                     let fn_decl = self.lower_fn_decl(&outer_decl, None, false, None);
 
                     self.with_new_scopes(|this| {
-                        // FIXME(cramertj) allow `async` non-`move` closures with
+                        // FIXME(cramertj): allow `async` non-`move` closures with arguments.
                         if capture_clause == CaptureBy::Ref &&
                             !decl.inputs.is_empty()
                         {
@@ -3883,13 +3884,13 @@ impl<'a> LoweringContext<'a> {
                                 are not currently supported",
                             )
                                 .help("consider using `let` statements to manually capture \
-                                        variables by reference before entering an \
+                                       variables by reference before entering an \
-                                        `async move` closure")
+                                       `async move` closure")
                                 .emit();
                         }
 
                         // Transform `async |x: u8| -> X { ... }` into
-                        // `|x: u8| future_from_generator(|| -> X { ... })`
+                        // `|x: u8| future_from_generator(|| -> X { ... })`.
                         let body_id = this.lower_body(Some(&outer_decl), |this| {
                             let async_ret_ty = if let FunctionRetTy::Ty(ty) = &decl.output {
                                 Some(&**ty)
@@ -3972,7 +3973,7 @@ impl<'a> LoweringContext<'a> {
             ExprKind::Index(ref el, ref er) => {
                 hir::ExprKind::Index(P(self.lower_expr(el)), P(self.lower_expr(er)))
             }
-            // Desugar `<start>..=<end>` to `std::ops::RangeInclusive::new(<start>, <end>)`
+            // Desugar `<start>..=<end>` into `std::ops::RangeInclusive::new(<start>, <end>)`.
             ExprKind::Range(Some(ref e1), Some(ref e2), RangeLimits::Closed) => {
                 let id = self.next_id();
                 let e1 = self.lower_expr(e1);
@@ -4106,11 +4107,11 @@ impl<'a> LoweringContext<'a> {
             ),
             ExprKind::Paren(ref ex) => {
                 let mut ex = self.lower_expr(ex);
-                // include parens in span, but only if it is a super-span.
+                // Include parens in span, but only if it is a super-span.
                 if e.span.contains(ex.span) {
                     ex.span = e.span;
                 }
-                // merge attributes into the inner expression.
+                // Merge attributes into the inner expression.
                 let mut attrs = e.attrs.clone();
                 attrs.extend::<Vec<_>>(ex.attrs.into());
                 ex.attrs = attrs;
@@ -4128,8 +4129,8 @@ impl<'a> LoweringContext<'a> {
                 hir::ExprKind::Yield(P(expr))
             }
 
-            // Desugar ExprIfLet
+            // Desugar `ExprIfLet`
-            // From: `if let <pat> = <sub_expr> <body> [<else_opt>]`
+            // from: `if let <pat> = <sub_expr> <body> [<else_opt>]`
             ExprKind::IfLet(ref pats, ref sub_expr, ref body, ref else_opt) => {
                 // to:
                 //
@@ -4173,8 +4174,8 @@ impl<'a> LoweringContext<'a> {
                 )
             }
 
-            // Desugar ExprWhileLet
+            // Desugar `ExprWhileLet`
-            // From: `[opt_ident]: while let <pat> = <sub_expr> <body>`
+            // from: `[opt_ident]: while let <pat> = <sub_expr> <body>`
             ExprKind::WhileLet(ref pats, ref sub_expr, ref body, opt_label) => {
                 // to:
                 //
@@ -4223,12 +4224,12 @@ impl<'a> LoweringContext<'a> {
                     self.lower_label(opt_label),
                     hir::LoopSource::WhileLet,
                 );
-                // add attributes to the outer returned expr node
+                // Add attributes to the outer returned expr node.
                 loop_expr
             }
 
-            // Desugar ExprForLoop
+            // Desugar `ExprForLoop`
-            // From: `[opt_ident]: for <pat> in <head> <body>`
+            // from: `[opt_ident]: for <pat> in <head> <body>`
             ExprKind::ForLoop(ref pat, ref head, ref body, opt_label) => {
                 // to:
                 //
@@ -4386,21 +4387,21 @@ impl<'a> LoweringContext<'a> {
                 ));
 
                 // `{ let _result = ...; _result }`
-                // underscore prevents an unused_variables lint if the head diverges
+                // Underscore prevents an `unused_variables` lint if the head diverges.
                 let result_ident = self.str_to_ident("_result");
                 let (let_stmt, let_stmt_binding) =
                     self.stmt_let(e.span, false, result_ident, match_expr);
 
                 let result = P(self.expr_ident(e.span, result_ident, let_stmt_binding));
                 let block = P(self.block_all(e.span, hir_vec![let_stmt], Some(result)));
-                // add the attributes to the outer returned expr node
+                // Add the attributes to the outer returned expr node.
                 return self.expr_block(block, e.attrs.clone());
             }
 
-            // Desugar ExprKind::Try
+            // Desugar `ExprKind::Try`
-            // From: `<expr>?`
+            // from: `<expr>?`
             ExprKind::Try(ref sub_expr) => {
-                // to:
+                // into:
                 //
                 // match Try::into_result(<expr>) {
                 //     Ok(val) => #[allow(unreachable_code)] val,
@@ -4414,7 +4415,7 @@ impl<'a> LoweringContext<'a> {
                 let unstable_span =
                     self.allow_internal_unstable(CompilerDesugaringKind::QuestionMark, e.span);
 
-                // Try::into_result(<expr>)
+                // `Try::into_result(<expr>)`
                 let discr = {
                     // expand <expr>
                     let sub_expr = self.lower_expr(sub_expr);
@@ -4425,9 +4426,9 @@ impl<'a> LoweringContext<'a> {
                     P(self.expr_call(e.span, path, hir_vec![sub_expr]))
                 };
 
-                // #[allow(unreachable_code)]
+                // `#[allow(unreachable_code)]`
                 let attr = {
-                    // allow(unreachable_code)
+                    // `allow(unreachable_code)`
                     let allow = {
                         let allow_ident = Ident::from_str("allow").with_span_pos(e.span);
                         let uc_ident = Ident::from_str("unreachable_code").with_span_pos(e.span);
@@ -4438,7 +4439,7 @@ impl<'a> LoweringContext<'a> {
                 };
                 let attrs = vec![attr];
 
-                // Ok(val) => #[allow(unreachable_code)] val,
+                // `Ok(val) => #[allow(unreachable_code)] val,`
                 let ok_arm = {
                     let val_ident = self.str_to_ident("val");
                     let val_pat = self.pat_ident(e.span, val_ident);
@@ -4453,8 +4454,8 @@ impl<'a> LoweringContext<'a> {
                     self.arm(hir_vec![ok_pat], val_expr)
                 };
 
-                // Err(err) => #[allow(unreachable_code)]
+                // `Err(err) => #[allow(unreachable_code)]
-                //             return Try::from_error(From::from(err)),
+                //              return Try::from_error(From::from(err)),`
                 let err_arm = {
                     let err_ident = self.str_to_ident("err");
                     let err_local = self.pat_ident(e.span, err_ident);
@@ -5014,7 +5015,7 @@ impl<'a> LoweringContext<'a> {
     /// error, depending on the mode.
     fn elided_path_lifetimes(&mut self, span: Span, count: usize) -> P<[hir::Lifetime]> {
         match self.anonymous_lifetime_mode {
-            // NB. We intentionally ignore the create-parameter mode here
+            // N.B., We intentionally ignore the create-parameter mode here
             // and instead "pass through" to resolve-lifetimes, which will then
             // report an error. This is because we don't want to support
             // impl elision for deprecated forms like

src/librustc/hir/map/blocks.rs

@@ -13,7 +13,7 @@
 //! it captures a common set of attributes that all "function-like
 //! things" (represented by `FnLike` instances) share.  For example,
 //! all `FnLike` instances have a type signature (be it explicit or
-//! inferred).  And all `FnLike` instances have a body, i.e. the code
+//! inferred).  And all `FnLike` instances have a body, i.e., the code
 //! that is run when the function-like thing it represents is invoked.
 //!
 //! With the above abstraction in place, one can treat the program
@@ -34,7 +34,7 @@ use syntax_pos::Span;
 /// More specifically, it is one of either:
 ///
 ///   - A function item,
-///   - A closure expr (i.e. an ExprKind::Closure), or
+///   - A closure expr (i.e., an ExprKind::Closure), or
 ///   - The default implementation for a trait method.
 ///
 /// To construct one, use the `Code::from_node` function.

src/librustc/hir/map/definitions.rs

@@ -150,10 +150,9 @@ impl Decodable for DefPathTable {
     }
 }
 
-
 /// The definition table containing node definitions.
-/// It holds the DefPathTable for local DefIds/DefPaths and it also stores a
+/// It holds the `DefPathTable` for local `DefId`s/`DefPath`s and it also stores a
-/// mapping from NodeIds to local DefIds.
+/// mapping from `NodeId`s to local `DefId`s.
 #[derive(Clone, Default)]
 pub struct Definitions {
     table: DefPathTable,

src/librustc/hir/map/mod.rs

@@ -286,9 +286,7 @@ impl<'hir> Map<'hir> {
 
         match node {
             Node::Item(item) => {
-                let def_id = || {
+                let def_id = || self.local_def_id(item.id);
-                    self.local_def_id(item.id)
-                };
 
                 match item.node {
                     ItemKind::Static(_, m, _) => Some(Def::Static(def_id(), m == MutMutable)),
@@ -383,7 +381,7 @@ impl<'hir> Map<'hir> {
     pub fn trait_item(&self, id: TraitItemId) -> &'hir TraitItem {
         self.read(id.node_id);
 
-        // NB: intentionally bypass `self.forest.krate()` so that we
+        // N.B., intentionally bypass `self.forest.krate()` so that we
         // do not trigger a read of the whole krate here
         self.forest.krate.trait_item(id)
     }
@@ -391,7 +389,7 @@ impl<'hir> Map<'hir> {
     pub fn impl_item(&self, id: ImplItemId) -> &'hir ImplItem {
         self.read(id.node_id);
 
-        // NB: intentionally bypass `self.forest.krate()` so that we
+        // N.B., intentionally bypass `self.forest.krate()` so that we
         // do not trigger a read of the whole krate here
         self.forest.krate.impl_item(id)
     }
@@ -399,7 +397,7 @@ impl<'hir> Map<'hir> {
     pub fn body(&self, id: BodyId) -> &'hir Body {
         self.read(id.node_id);
 
-        // NB: intentionally bypass `self.forest.krate()` so that we
+        // N.B., intentionally bypass `self.forest.krate()` so that we
         // do not trigger a read of the whole krate here
         self.forest.krate.body(id)
     }
@@ -413,7 +411,7 @@ impl<'hir> Map<'hir> {
     }
 
     /// Returns the `NodeId` that corresponds to the definition of
-    /// which this is the body of, i.e. a `fn`, `const` or `static`
+    /// which this is the body of, i.e., a `fn`, `const` or `static`
     /// item (possibly associated), a closure, or a `hir::AnonConst`.
     pub fn body_owner(&self, BodyId { node_id }: BodyId) -> NodeId {
         let parent = self.get_parent_node(node_id);
@@ -484,7 +482,7 @@ impl<'hir> Map<'hir> {
     pub fn trait_impls(&self, trait_did: DefId) -> &'hir [NodeId] {
         self.dep_graph.read(DepNode::new_no_params(DepKind::AllLocalTraitImpls));
 
-        // NB: intentionally bypass `self.forest.krate()` so that we
+        // N.B., intentionally bypass `self.forest.krate()` so that we
         // do not trigger a read of the whole krate here
         self.forest.krate.trait_impls.get(&trait_did).map_or(&[], |xs| &xs[..])
     }
@@ -492,7 +490,7 @@ impl<'hir> Map<'hir> {
     pub fn trait_auto_impl(&self, trait_did: DefId) -> Option<NodeId> {
         self.dep_graph.read(DepNode::new_no_params(DepKind::AllLocalTraitImpls));
 
-        // NB: intentionally bypass `self.forest.krate()` so that we
+        // N.B., intentionally bypass `self.forest.krate()` so that we
         // do not trigger a read of the whole krate here
         self.forest.krate.trait_auto_impl.get(&trait_did).cloned()
     }
@@ -565,14 +563,14 @@ impl<'hir> Map<'hir> {
         result
     }
 
-    /// Similar to get_parent, returns the parent node id or id if there is no
+    /// Similar to `get_parent`; returns the parent node-id, or own `id` if there is
-    /// parent. Note that the parent may be CRATE_NODE_ID, which is not itself
+    /// no parent. Note that the parent may be `CRATE_NODE_ID`, which is not itself
     /// present in the map -- so passing the return value of get_parent_node to
     /// get may actually panic.
     /// This function returns the immediate parent in the AST, whereas get_parent
     /// returns the enclosing item. Note that this might not be the actual parent
     /// node in the AST - some kinds of nodes are not in the map and these will
-    /// never appear as the parent_node. So you can always walk the parent_nodes
+    /// never appear as the parent_node. So you can always walk the `parent_nodes`
     /// from a node to the root of the ast (unless you get the same id back here
     /// that can happen if the id is not in the map itself or is just weird).
     pub fn get_parent_node(&self, id: NodeId) -> NodeId {
@@ -608,7 +606,7 @@ impl<'hir> Map<'hir> {
 
     /// If there is some error when walking the parents (e.g., a node does not
     /// have a parent in the map or a node can't be found), then we return the
-    /// last good node id we found. Note that reaching the crate root (id == 0),
+    /// last good node id we found. Note that reaching the crate root (`id == 0`),
     /// is not an error, since items in the crate module have the crate root as
     /// parent.
     fn walk_parent_nodes<F, F2>(&self,
@@ -644,7 +642,7 @@ impl<'hir> Map<'hir> {
         }
     }
 
-    /// Retrieve the NodeId for `id`'s enclosing method, unless there's a
+    /// Retrieve the `NodeId` for `id`'s enclosing method, unless there's a
     /// `while` or `loop` before reaching it, as block tail returns are not
     /// available in them.
     ///
@@ -691,7 +689,7 @@ impl<'hir> Map<'hir> {
         self.walk_parent_nodes(id, match_fn, match_non_returning_block).ok()
     }
 
-    /// Retrieve the NodeId for `id`'s parent item, or `id` itself if no
+    /// Retrieve the `NodeId` for `id`'s parent item, or `id` itself if no
     /// parent item is in this map. The "parent item" is the closest parent node
     /// in the HIR which is recorded by the map and is an item, either an item
     /// in a module, trait, or impl.
@@ -708,13 +706,13 @@ impl<'hir> Map<'hir> {
         }
     }
 
-    /// Returns the DefId of `id`'s nearest module parent, or `id` itself if no
+    /// Returns the `DefId` of `id`'s nearest module parent, or `id` itself if no
     /// module parent is in this map.
     pub fn get_module_parent(&self, id: NodeId) -> DefId {
         self.local_def_id(self.get_module_parent_node(id))
     }
 
-    /// Returns the NodeId of `id`'s nearest module parent, or `id` itself if no
+    /// Returns the `NodeId` of `id`'s nearest module parent, or `id` itself if no
     /// module parent is in this map.
     pub fn get_module_parent_node(&self, id: NodeId) -> NodeId {
         match self.walk_parent_nodes(id, |node| match *node {
@@ -727,7 +725,7 @@ impl<'hir> Map<'hir> {
     }
 
     /// Returns the nearest enclosing scope. A scope is an item or block.
-    /// FIXME it is not clear to me that all items qualify as scopes - statics
+    /// FIXME: it is not clear to me that all items qualify as scopes -- statics
     /// and associated types probably shouldn't, for example. Behavior in this
     /// regard should be expected to be highly unstable.
     pub fn get_enclosing_scope(&self, id: NodeId) -> Option<NodeId> {

src/librustc/hir/mod.rs

@@ -8,7 +8,9 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-// The Rust HIR.
+// HIR datatypes. See the [rustc guide] for more info.
+//!
+//! [rustc guide]: https://rust-lang.github.io/rustc-guide/hir.html
 
 pub use self::BlockCheckMode::*;
 pub use self::CaptureClause::*;
@@ -71,7 +73,7 @@ pub mod print;
 
 /// A HirId uniquely identifies a node in the HIR of the current crate. It is
 /// composed of the `owner`, which is the DefIndex of the directly enclosing
-/// hir::Item, hir::TraitItem, or hir::ImplItem (i.e. the closest "item-like"),
+/// hir::Item, hir::TraitItem, or hir::ImplItem (i.e., the closest "item-like"),
 /// and the `local_id` which is unique within the given owner.
 ///
 /// This two-level structure makes for more stable values: One can move an item
@@ -181,7 +183,7 @@ pub enum ParamName {
     Plain(Ident),
 
     /// Synthetic name generated when user elided a lifetime in an impl header,
-    /// e.g. the lifetimes in cases like these:
+    /// e.g., the lifetimes in cases like these:
     ///
     ///     impl Foo for &u32
     ///     impl Foo<'_> for u32
@@ -197,7 +199,7 @@ pub enum ParamName {
 
     /// Indicates an illegal name was given and an error has been
     /// repored (so we should squelch other derived errors). Occurs
-    /// when e.g. `'_` is used in the wrong place.
+    /// when e.g., `'_` is used in the wrong place.
     Error,
 }
 
@@ -222,7 +224,7 @@ pub enum LifetimeName {
     /// User-given names or fresh (synthetic) names.
     Param(ParamName),
 
-    /// User typed nothing. e.g. the lifetime in `&u32`.
+    /// User typed nothing. e.g., the lifetime in `&u32`.
     Implicit,
 
     /// Indicates an error during lowering (usually `'_` in wrong place)
@@ -351,7 +353,7 @@ pub struct PathSegment {
     /// Whether to infer remaining type parameters, if any.
     /// This only applies to expression and pattern paths, and
     /// out of those only the segments with no type parameters
-    /// to begin with, e.g. `Vec::new` is `<Vec<..>>::new::<..>`.
+    /// to begin with, e.g., `Vec::new` is `<Vec<..>>::new::<..>`.
     pub infer_types: bool,
 }
 
@@ -388,7 +390,7 @@ impl PathSegment {
     }
 
     // FIXME: hack required because you can't create a static
-    // GenericArgs, so you can't just return a &GenericArgs.
+    // `GenericArgs`, so you can't just return a `&GenericArgs`.
     pub fn with_generic_args<F, R>(&self, f: F) -> R
         where F: FnOnce(&GenericArgs) -> R
     {
@@ -514,17 +516,17 @@ pub type GenericBounds = HirVec<GenericBound>;
 
 #[derive(Copy, Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Debug)]
 pub enum LifetimeParamKind {
-    // Indicates that the lifetime definition was explicitly declared, like:
+    // Indicates that the lifetime definition was explicitly declared (e.g., in
-    // `fn foo<'a>(x: &'a u8) -> &'a u8 { x }`
+    // `fn foo<'a>(x: &'a u8) -> &'a u8 { x }`).
     Explicit,
 
     // Indicates that the lifetime definition was synthetically added
-    // as a result of an in-band lifetime usage like:
+    // as a result of an in-band lifetime usage (e.g., in
-    // `fn foo(x: &'a u8) -> &'a u8 { x }`
+    // `fn foo(x: &'a u8) -> &'a u8 { x }`).
     InBand,
 
-    // Indication that the lifetime was elided like both cases here:
+    // Indication that the lifetime was elided (e.g., in both cases in
-    // `fn foo(x: &u8) -> &'_ u8 { x }`
+    // `fn foo(x: &u8) -> &'_ u8 { x }`).
     Elided,
 
     // Indication that the lifetime name was somehow in error.
@@ -533,7 +535,7 @@ pub enum LifetimeParamKind {
 
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub enum GenericParamKind {
-    /// A lifetime definition, eg `'a: 'b + 'c + 'd`.
+    /// A lifetime definition (e.g., `'a: 'b + 'c + 'd`).
     Lifetime {
         kind: LifetimeParamKind,
     },
@@ -637,11 +639,11 @@ impl WhereClause {
 /// A single predicate in a `where` clause
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub enum WherePredicate {
-    /// A type binding, eg `for<'c> Foo: Send+Clone+'c`
+    /// A type binding (e.g., `for<'c> Foo: Send + Clone + 'c`).
     BoundPredicate(WhereBoundPredicate),
-    /// A lifetime predicate, e.g. `'a: 'b+'c`
+    /// A lifetime predicate (e.g., `'a: 'b + 'c`).
     RegionPredicate(WhereRegionPredicate),
-    /// An equality predicate (unsupported)
+    /// An equality predicate (unsupported).
     EqPredicate(WhereEqPredicate),
 }
 
@@ -667,7 +669,7 @@ pub struct WhereBoundPredicate {
     pub bounds: GenericBounds,
 }
 
-/// A lifetime predicate, e.g. `'a: 'b+'c`
+/// A lifetime predicate, e.g., `'a: 'b+'c`
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct WhereRegionPredicate {
     pub span: Span,
@@ -675,7 +677,7 @@ pub struct WhereRegionPredicate {
     pub bounds: GenericBounds,
 }
 
-/// An equality predicate (unsupported), e.g. `T=int`
+/// An equality predicate (unsupported), e.g., `T=int`
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct WhereEqPredicate {
     pub id: NodeId,
@@ -697,7 +699,7 @@ pub struct Crate {
     pub span: Span,
     pub exported_macros: HirVec<MacroDef>,
 
-    // NB: We use a BTreeMap here so that `visit_all_items` iterates
+    // N.B., we use a BTreeMap here so that `visit_all_items` iterates
     // over the ids in increasing order. In principle it should not
     // matter what order we visit things in, but in *practice* it
     // does, because it can affect the order in which errors are
@@ -932,11 +934,11 @@ pub enum PatKind {
 
     /// A fresh binding `ref mut binding @ OPT_SUBPATTERN`.
     /// The `NodeId` is the canonical ID for the variable being bound,
-    /// e.g. in `Ok(x) | Err(x)`, both `x` use the same canonical ID,
+    /// e.g., in `Ok(x) | Err(x)`, both `x` use the same canonical ID,
     /// which is the pattern ID of the first `x`.
     Binding(BindingAnnotation, NodeId, Ident, Option<P<Pat>>),
 
-    /// A struct or struct variant pattern, e.g. `Variant {x, y, ..}`.
+    /// A struct or struct variant pattern, e.g., `Variant {x, y, ..}`.
     /// The `bool` is `true` in the presence of a `..`.
     Struct(QPath, HirVec<Spanned<FieldPat>>, bool),
 
@@ -954,11 +956,11 @@ pub enum PatKind {
     Tuple(HirVec<P<Pat>>, Option<usize>),
     /// A `box` pattern
     Box(P<Pat>),
-    /// A reference pattern, e.g. `&mut (a, b)`
+    /// A reference pattern, e.g., `&mut (a, b)`
     Ref(P<Pat>, Mutability),
     /// A literal
     Lit(P<Expr>),
-    /// A range pattern, e.g. `1...2` or `1..2`
+    /// A range pattern, e.g., `1...2` or `1..2`
     Range(P<Expr>, P<Expr>, RangeEnd),
     /// `[a, b, ..i, y, z]` is represented as:
     ///     `PatKind::Slice(box [a, b], Some(i), box [y, z])`
@@ -1319,8 +1321,8 @@ pub enum BodyOwnerKind {
 
 /// A constant (expression) that's not an item or associated item,
 /// but needs its own `DefId` for type-checking, const-eval, etc.
-/// These are usually found nested inside types (e.g. array lengths)
+/// These are usually found nested inside types (e.g., array lengths)
-/// or expressions (e.g. repeat counts), and also used to define
+/// or expressions (e.g., repeat counts), and also used to define
 /// explicit discriminant values for enum variants.
 #[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Debug)]
 pub struct AnonConst {
@@ -1541,12 +1543,12 @@ pub enum QPath {
     /// Path to a definition, optionally "fully-qualified" with a `Self`
     /// type, if the path points to an associated item in a trait.
     ///
-    /// E.g. an unqualified path like `Clone::clone` has `None` for `Self`,
+    /// e.g., an unqualified path like `Clone::clone` has `None` for `Self`,
     /// while `<Vec<T> as Clone>::clone` has `Some(Vec<T>)` for `Self`,
     /// even though they both have the same two-segment `Clone::clone` `Path`.
     Resolved(Option<P<Ty>>, P<Path>),
 
-    /// Type-related paths, e.g. `<T>::default` or `<T>::Output`.
+    /// Type-related paths, e.g., `<T>::default` or `<T>::Output`.
     /// Will be resolved by type-checking to an associated item.
     ///
     /// UFCS source paths can desugar into this, with `Vec::new` turning into
@@ -1633,7 +1635,7 @@ pub enum CaptureClause {
     CaptureByRef,
 }
 
-// NB: If you change this, you'll probably want to change the corresponding
+// N.B., if you change this, you'll probably want to change the corresponding
 // type structure in middle/ty.rs as well.
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct MutTy {
@@ -1792,14 +1794,14 @@ pub enum TyKind {
     Ptr(MutTy),
     /// A reference (`&'a T` or `&'a mut T`)
     Rptr(Lifetime, MutTy),
-    /// A bare function (e.g. `fn(usize) -> bool`)
+    /// A bare function (e.g., `fn(usize) -> bool`)
     BareFn(P<BareFnTy>),
     /// The never type (`!`)
     Never,
     /// A tuple (`(A, B, C, D,...)`)
     Tup(HirVec<Ty>),
     /// A path to a type definition (`module::module::...::Type`), or an
-    /// associated type, e.g. `<Vec<T> as Trait>::Type` or `<T>::Target`.
+    /// associated type, e.g., `<Vec<T> as Trait>::Type` or `<T>::Target`.
     ///
     /// Type parameters may be stored in each `PathSegment`.
     Path(QPath),
@@ -1814,7 +1816,7 @@ pub enum TyKind {
     TraitObject(HirVec<PolyTraitRef>, Lifetime),
     /// Unused for now
     Typeof(AnonConst),
-    /// TyKind::Infer means the type should be inferred instead of it having been
+    /// `TyKind::Infer` means the type should be inferred instead of it having been
     /// specified. This can appear anywhere in a type.
     Infer,
     /// Placeholder for a type that has failed to be defined.
@@ -2017,7 +2019,7 @@ pub struct VariantKind {
     pub name: Name,
     pub attrs: HirVec<Attribute>,
     pub data: VariantData,
-    /// Explicit discriminant, eg `Foo = 1`
+    /// Explicit discriminant, e.g., `Foo = 1`
     pub disr_expr: Option<AnonConst>,
 }
 
@@ -2025,15 +2027,15 @@ pub type Variant = Spanned<VariantKind>;
 
 #[derive(Copy, Clone, PartialEq, RustcEncodable, RustcDecodable, Debug)]
 pub enum UseKind {
-    /// One import, e.g. `use foo::bar` or `use foo::bar as baz`.
+    /// One import, e.g., `use foo::bar` or `use foo::bar as baz`.
     /// Also produced for each element of a list `use`, e.g.
     // `use foo::{a, b}` lowers to `use foo::a; use foo::b;`.
     Single,
 
-    /// Glob import, e.g. `use foo::*`.
+    /// Glob import, e.g., `use foo::*`.
     Glob,
 
-    /// Degenerate list import, e.g. `use foo::{a, b}` produces
+    /// Degenerate list import, e.g., `use foo::{a, b}` produces
     /// an additional `use foo::{}` for performing checks such as
     /// unstable feature gating. May be removed in the future.
     ListStem,
@@ -2196,7 +2198,7 @@ pub struct FnHeader {
 pub enum ItemKind {
     /// An `extern crate` item, with optional *original* crate name if the crate was renamed.
     ///
-    /// E.g. `extern crate foo` or `extern crate foo_bar as foo`
+    /// e.g., `extern crate foo` or `extern crate foo_bar as foo`
     ExternCrate(Option<Name>),
 
     /// `use foo::bar::*;` or `use foo::bar::baz as quux;`
@@ -2218,15 +2220,15 @@ pub enum ItemKind {
     ForeignMod(ForeignMod),
     /// Module-level inline assembly (from global_asm!)
     GlobalAsm(P<GlobalAsm>),
-    /// A type alias, e.g. `type Foo = Bar<u8>`
+    /// A type alias, e.g., `type Foo = Bar<u8>`
     Ty(P<Ty>, Generics),
-    /// An existential type definition, e.g. `existential type Foo: Bar;`
+    /// An existential type definition, e.g., `existential type Foo: Bar;`
     Existential(ExistTy),
-    /// An enum definition, e.g. `enum Foo<A, B> {C<A>, D<B>}`
+    /// An enum definition, e.g., `enum Foo<A, B> {C<A>, D<B>}`
     Enum(EnumDef, Generics),
-    /// A struct definition, e.g. `struct Foo<A> {x: A}`
+    /// A struct definition, e.g., `struct Foo<A> {x: A}`
     Struct(VariantData, Generics),
-    /// A union definition, e.g. `union Foo<A, B> {x: A, y: B}`
+    /// A union definition, e.g., `union Foo<A, B> {x: A, y: B}`
     Union(VariantData, Generics),
     /// Represents a Trait Declaration
     Trait(IsAuto, Unsafety, Generics, GenericBounds, HirVec<TraitItemRef>),

src/librustc/hir/pat_util.rs

@@ -101,7 +101,7 @@ impl hir::Pat {
     }
 
     /// Checks if the pattern contains any patterns that bind something to
-    /// an ident, e.g. `foo`, or `Foo(foo)` or `foo @ Bar(..)`.
+    /// an ident, e.g., `foo`, or `Foo(foo)` or `foo @ Bar(..)`.
     pub fn contains_bindings(&self) -> bool {
         let mut contains_bindings = false;
         self.walk(|p| {
@@ -116,7 +116,7 @@ impl hir::Pat {
     }
 
     /// Checks if the pattern contains any patterns that bind something to
-    /// an ident or wildcard, e.g. `foo`, or `Foo(_)`, `foo @ Bar(..)`,
+    /// an ident or wildcard, e.g., `foo`, or `Foo(_)`, `foo @ Bar(..)`,
     pub fn contains_bindings_or_wild(&self) -> bool {
         let mut contains_bindings = false;
         self.walk(|p| {

src/librustc/hir/print.rs

@@ -2448,8 +2448,8 @@ fn bin_op_to_assoc_op(op: hir::BinOpKind) -> AssocOp {
     }
 }
 
-/// Expressions that syntactically contain an "exterior" struct literal i.e. not surrounded by any
+/// Expressions that syntactically contain an "exterior" struct literal i.e., not surrounded by any
-/// parens or other delimiters, e.g. `X { y: 1 }`, `X { y: 1 }.method()`, `foo == X { y: 1 }` and
+/// parens or other delimiters, e.g., `X { y: 1 }`, `X { y: 1 }.method()`, `foo == X { y: 1 }` and
 /// `X { y: 1 } == foo` all do, but `(X { y: 1 }) == foo` does not.
 fn contains_exterior_struct_lit(value: &hir::Expr) -> bool {
     match value.node {

src/librustc/ich/hcx.rs

@@ -45,7 +45,7 @@ fn compute_ignored_attr_names() -> FxHashSet<Symbol> {
 /// This is the context state available during incr. comp. hashing. It contains
 /// enough information to transform DefIds and HirIds into stable DefPaths (i.e.
 /// a reference to the TyCtxt) and it holds a few caches for speeding up various
-/// things (e.g. each DefId/DefPath is only hashed once).
+/// things (e.g., each DefId/DefPath is only hashed once).
 #[derive(Clone)]
 pub struct StableHashingContext<'a> {
     sess: &'a Session,

src/librustc/infer/combine.rs

@@ -371,7 +371,7 @@ impl<'cx, 'gcx, 'tcx> TypeRelation<'cx, 'gcx, 'tcx> for Generalizer<'cx, 'gcx, '
         if self.ambient_variance == ty::Variance::Invariant {
             // Avoid fetching the variance if we are in an invariant
             // context; no need, and it can induce dependency cycles
-            // (e.g. #41849).
+            // (e.g., #41849).
             relate::relate_substs(self, None, a_subst, b_subst)
         } else {
             let opt_variances = self.tcx().variances_of(item_def_id);

src/librustc/infer/equate.rs

@@ -47,9 +47,9 @@ impl<'combine, 'infcx, 'gcx, 'tcx> TypeRelation<'infcx, 'gcx, 'tcx>
                           b_subst: &'tcx Substs<'tcx>)
                           -> RelateResult<'tcx, &'tcx Substs<'tcx>>
     {
-        // NB: Once we are equating types, we don't care about
+        // N.B., once we are equating types, we don't care about
         // variance, so don't try to lookup the variance here. This
-        // also avoids some cycles (e.g. #41849) since looking up
+        // also avoids some cycles (e.g., #41849) since looking up
         // variance requires computing types which can require
         // performing trait matching (which then performs equality
         // unification).

src/librustc/infer/error_reporting/nice_region_error/find_anon_type.rs

@@ -30,7 +30,7 @@ impl<'a, 'gcx, 'tcx> NiceRegionError<'a, 'gcx, 'tcx> {
     ///    { x.push(y); }
     /// ```
     /// The function returns the nested type corresponding to the anonymous region
-    /// for e.g. `&u8` and Vec<`&u8`.
+    /// for e.g., `&u8` and Vec<`&u8`.
     pub(super) fn find_anon_type(
         &self,
         region: Region<'tcx>,
@@ -97,7 +97,7 @@ struct FindNestedTypeVisitor<'a, 'gcx: 'a + 'tcx, 'tcx: 'a> {
     // associated with the anonymous region we are looking for.
     bound_region: ty::BoundRegion,
     // The type where the anonymous lifetime appears
-    // for e.g. Vec<`&u8`> and <`&u8`>
+    // for e.g., Vec<`&u8`> and <`&u8`>
     found_type: Option<&'gcx hir::Ty>,
     current_index: ty::DebruijnIndex,
 }

src/librustc/infer/higher_ranked/mod.rs

@@ -542,7 +542,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
     /// Pops the placeholder regions found in `placeholder_map` from the region
     /// inference context. Whenever you create placeholder regions via
     /// `replace_bound_vars_with_placeholders`, they must be popped before you
-    /// commit the enclosing snapshot (if you do not commit, e.g. within a
+    /// commit the enclosing snapshot (if you do not commit, e.g., within a
     /// probe or as a result of an error, then this is not necessary, as
     /// popping happens as part of the rollback).
     ///

src/librustc/infer/mod.rs

@@ -219,7 +219,7 @@ pub struct InferCtxt<'a, 'gcx: 'a + 'tcx, 'tcx: 'a> {
     /// `UniverseIndex::root()` but grows from there as we enter
     /// universal quantifiers.
     ///
-    /// NB: At present, we exclude the universal quantifiers on the
+    /// N.B., at present, we exclude the universal quantifiers on the
     /// item we are type-checking, and just consider those names as
     /// part of the root universe. So this would only get incremented
     /// when we enter into a higher-ranked (`for<..>`) type or trait
@@ -732,7 +732,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
             region_obligations_snapshot: self.region_obligations.borrow().len(),
             universe: self.universe(),
             was_in_snapshot: in_snapshot,
-            // Borrow tables "in progress" (i.e. during typeck)
+            // Borrow tables "in progress" (i.e., during typeck)
             // to ban writes from within a snapshot to them.
             _in_progress_tables: self.in_progress_tables.map(|tables| tables.borrow()),
         }
@@ -1047,7 +1047,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
                 // type parameter definition. The substitutions are
                 // for actual parameters that may be referred to by
                 // the default of this type parameter, if it exists.
-                // E.g. `struct Foo<A, B, C = (A, B)>(...);` when
+                // e.g., `struct Foo<A, B, C = (A, B)>(...);` when
                 // used in a path such as `Foo::<T, U>::new()` will
                 // use an inference variable for `C` with `[T, U]`
                 // as the substitutions for the default, `(T, U)`.
@@ -1261,7 +1261,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
          * Where possible, replaces type/int/float variables in
          * `value` with their final value. Note that region variables
          * are unaffected. If a type variable has not been unified, it
-         * is left as is.  This is an idempotent operation that does
+         * is left as is. This is an idempotent operation that does
          * not affect inference state in any way and so you can do it
          * at will.
          */
@@ -1298,7 +1298,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
         /*!
          * Attempts to resolve all type/region variables in
          * `value`. Region inference must have been run already (e.g.,
-         * by calling `resolve_regions_and_report_errors`).  If some
+         * by calling `resolve_regions_and_report_errors`). If some
          * variable was never unified, an `Err` results.
          *
          * This method is idempotent, but it not typically not invoked
@@ -1331,7 +1331,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
         let actual_ty = self.resolve_type_vars_if_possible(&actual_ty);
         debug!("type_error_struct_with_diag({:?}, {:?})", sp, actual_ty);
 
-        // Don't report an error if actual type is Error.
+        // Don't report an error if actual type is `Error`.
         if actual_ty.references_error() {
             return self.tcx.sess.diagnostic().struct_dummy();
         }

src/librustc/infer/nll_relate/mod.rs

@@ -15,7 +15,7 @@
 //!
 //! Here are the key differences:
 //!
-//! - This code may choose to bypass some checks (e.g. the occurs check)
+//! - This code may choose to bypass some checks (e.g., the occurs check)
 //!   in the case where we know that there are no unbound type inference
 //!   variables. This is the case for NLL, because at NLL time types are fully
 //!   inferred up-to regions.
@@ -97,7 +97,7 @@ pub trait TypeRelatingDelegate<'tcx> {
     /// region that is instantiated existentially. This creates an
     /// inference variable, typically.
     ///
-    /// So e.g. if you have `for<'a> fn(..) <: for<'b> fn(..)`, then
+    /// So e.g., if you have `for<'a> fn(..) <: for<'b> fn(..)`, then
     /// we will invoke this method to instantiate `'a` with an
     /// inference variable (though `'b` would be instantiated first,
     /// as a placeholder).
@@ -107,7 +107,7 @@ pub trait TypeRelatingDelegate<'tcx> {
     /// higher-ranked region that is instantiated universally.
     /// This creates a new region placeholder, typically.
     ///
-    /// So e.g. if you have `for<'a> fn(..) <: for<'b> fn(..)`, then
+    /// So e.g., if you have `for<'a> fn(..) <: for<'b> fn(..)`, then
     /// we will invoke this method to instantiate `'b` with a
     /// placeholder region.
     fn next_placeholder_region(&mut self, placeholder: ty::PlaceholderRegion) -> ty::Region<'tcx>;

src/librustc/infer/opaque_types/mod.rs

@@ -761,7 +761,7 @@ impl<'a, 'gcx, 'tcx> Instantiator<'a, 'gcx, 'tcx> {
         );
 
         // Use the same type variable if the exact same Opaque appears more
-        // than once in the return type (e.g. if it's passed to a type alias).
+        // than once in the return type (e.g., if it's passed to a type alias).
         if let Some(opaque_defn) = self.opaque_types.get(&def_id) {
             return opaque_defn.concrete_ty;
         }
@@ -783,7 +783,7 @@ impl<'a, 'gcx, 'tcx> Instantiator<'a, 'gcx, 'tcx> {
         );
 
         // make sure that we are in fact defining the *entire* type
-        // e.g. `existential type Foo<T: Bound>: Bar;` needs to be
+        // e.g., `existential type Foo<T: Bound>: Bar;` needs to be
         // defined by a function like `fn foo<T: Bound>() -> Foo<T>`.
         debug!(
             "instantiate_opaque_types: param_env: {:#?}",

src/librustc/infer/outlives/obligations.rs

@@ -408,7 +408,7 @@ where
 
         // Remove outlives bounds that we get from the environment but
         // which are also deducable from the trait. This arises (cc
-        // #55756) in cases where you have e.g. `<T as Foo<'a>>::Item:
+        // #55756) in cases where you have e.g., `<T as Foo<'a>>::Item:
         // 'a` in the environment but `trait Foo<'b> { type Item: 'b
         // }` in the trait definition.
         approx_env_bounds.retain(|bound| {

src/librustc/infer/region_constraints/mod.rs

@@ -60,7 +60,7 @@ pub struct RegionConstraintCollector<'tcx> {
     /// which can never be rolled back.
     undo_log: Vec<UndoLog<'tcx>>,
 
-    /// The number of open snapshots, i.e. those that haven't been committed or
+    /// The number of open snapshots, i.e., those that haven't been committed or
     /// rolled back.
     num_open_snapshots: usize,
 
@@ -607,7 +607,7 @@ impl<'tcx> RegionConstraintCollector<'tcx> {
 
         // never overwrite an existing (constraint, origin) - only insert one if it isn't
         // present in the map yet. This prevents origins from outside the snapshot being
-        // replaced with "less informative" origins e.g. during calls to `can_eq`
+        // replaced with "less informative" origins e.g., during calls to `can_eq`
         let in_snapshot = self.in_snapshot();
         let undo_log = &mut self.undo_log;
         self.data.constraints.entry(constraint).or_insert_with(|| {

src/librustc/infer/type_variable.rs

@@ -175,7 +175,7 @@ impl<'tcx> TypeVariableTable<'tcx> {
     /// Creates a new type variable.
     ///
     /// - `diverging`: indicates if this is a "diverging" type
-    ///   variable, e.g.  one created as the type of a `return`
+    ///   variable, e.g.,  one created as the type of a `return`
     ///   expression. The code in this module doesn't care if a
     ///   variable is diverging, but the main Rust type-checker will
     ///   sometimes "unify" such variables with the `!` or `()` types.

src/librustc/lib.rs

@@ -119,7 +119,7 @@ extern crate test;
 #[macro_use]
 mod macros;
 
-// NB: This module needs to be declared first so diagnostics are
+// N.B., this module needs to be declared first so diagnostics are
 // registered before they are used.
 pub mod diagnostics;
 

src/librustc/lint/builtin.rs

@@ -174,7 +174,7 @@ declare_lint! {
 declare_lint! {
     pub LEGACY_DIRECTORY_OWNERSHIP,
     Deny,
-    "non-inline, non-`#[path]` modules (e.g. `mod foo;`) were erroneously allowed in some files \
+    "non-inline, non-`#[path]` modules (e.g., `mod foo;`) were erroneously allowed in some files \
      not named `mod.rs`"
 }
 
@@ -366,7 +366,7 @@ pub mod parser {
 }
 
 /// Does nothing as a lint pass, but registers some `Lint`s
-/// which are used by other parts of the compiler.
+/// that are used by other parts of the compiler.
 #[derive(Copy, Clone)]
 pub struct HardwiredLints;
 

src/librustc/lint/context.rs

@@ -1270,7 +1270,7 @@ pub fn check_ast_crate(
     //
     // Rustdoc runs everybody-loops before the early lints and removes
     // function bodies, so it's totally possible for linted
-    // node ids to not exist (e.g. macros defined within functions for the
+    // node ids to not exist (e.g., macros defined within functions for the
     // unused_macro lint) anymore. So we only run this check
     // when we're not in rustdoc mode. (see issue #47639)
     if !sess.opts.actually_rustdoc {

src/librustc/lint/levels.rs

@@ -66,7 +66,7 @@ impl LintLevelSets {
         for &(ref lint_name, level) in &sess.opts.lint_opts {
             store.check_lint_name_cmdline(sess, &lint_name, level);
 
-            // If the cap is less than this specified level, e.g. if we've got
+            // If the cap is less than this specified level, e.g., if we've got
             // `--cap-lints allow` but we've also got `-D foo` then we ignore
             // this specification as the lint cap will set it to allow anyway.
             let level = cmp::min(level, self.lint_cap);
@@ -191,7 +191,7 @@ impl<'a> LintLevelsBuilder<'a> {
     /// * It'll validate all lint-related attributes in `attrs`
     /// * It'll mark all lint-related attributes as used
     /// * Lint levels will be updated based on the attributes provided
-    /// * Lint attributes are validated, e.g. a #[forbid] can't be switched to
+    /// * Lint attributes are validated, e.g., a #[forbid] can't be switched to
     ///   #[allow]
     ///
     /// Don't forget to call `pop`!

src/librustc/lint/mod.rs

@@ -67,7 +67,7 @@ pub struct Lint {
     /// `declare_lint!()` invocations to follow the convention of upper-case
     /// statics without repeating the name.
     ///
-    /// The name is written with underscores, e.g. "unused_imports".
+    /// The name is written with underscores, e.g., "unused_imports".
     /// On the command line, underscores become dashes.
     pub name: &'static str,
 
@@ -76,7 +76,7 @@ pub struct Lint {
 
     /// Description of the lint or the issue it detects.
     ///
-    /// e.g. "imports that are never used"
+    /// e.g., "imports that are never used"
     pub desc: &'static str,
 
     /// Starting at the given edition, default to the given lint level. If this is `None`, then use
@@ -173,7 +173,7 @@ pub type LintArray = Vec<&'static Lint>;
 pub trait LintPass {
     /// Get descriptions of the lints this `LintPass` object can emit.
     ///
-    /// NB: there is no enforcement that the object only emits lints it registered.
+    /// N.B., there is no enforcement that the object only emits lints it registered.
     /// And some `rustc` internal `LintPass`es register lints to be emitted by other
     /// parts of the compiler. If you want enforced access restrictions for your
     /// `Lint`, make it a private `static` item in its own module.

src/librustc/middle/cstore.rs

@@ -59,7 +59,7 @@ pub enum DepKind {
     /// A dependency that is only used for its macros.
     MacrosOnly,
     /// A dependency that is always injected into the dependency list and so
-    /// doesn't need to be linked to an rlib, e.g. the injected allocator.
+    /// doesn't need to be linked to an rlib, e.g., the injected allocator.
     Implicit,
     /// A dependency that is required by an rlib version of this crate.
     /// Ordinary `extern crate`s result in `Explicit` dependencies.

src/librustc/middle/dead.rs

@@ -311,7 +311,7 @@ fn has_allow_dead_code_or_lang_attr(tcx: TyCtxt<'_, '_, '_>,
     let cg_attrs = tcx.codegen_fn_attrs(def_id);
 
     // #[used], #[no_mangle], #[export_name], etc also keeps the item alive
-    // forcefully, e.g. for placing it in a specific section.
+    // forcefully, e.g., for placing it in a specific section.
     if cg_attrs.contains_extern_indicator() ||
         cg_attrs.flags.contains(CodegenFnAttrFlags::USED) {
         return true;

src/librustc/middle/dependency_format.rs

@@ -201,7 +201,7 @@ fn calculate_type<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>,
     // static libraries.
     //
     // If the crate hasn't been included yet and it's not actually required
-    // (e.g. it's an allocator) then we skip it here as well.
+    // (e.g., it's an allocator) then we skip it here as well.
     for &cnum in tcx.crates().iter() {
         let src = tcx.used_crate_source(cnum);
         if src.dylib.is_none() &&
@@ -306,7 +306,7 @@ fn attempt_static<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>) -> Option<DependencyLis
 
 // Given a list of how to link upstream dependencies so far, ensure that an
 // injected dependency is activated. This will not do anything if one was
-// transitively included already (e.g. via a dylib or explicitly so).
+// transitively included already (e.g., via a dylib or explicitly so).
 //
 // If an injected dependency was not found then we're guaranteed the
 // metadata::creader module has injected that dependency (not listed as

src/librustc/middle/entry.rs

@@ -87,7 +87,7 @@ pub fn find_entry_point(session: &Session,
     configure_main(&mut ctxt, crate_name);
 }
 
-// Beware, this is duplicated in libsyntax/entry.rs, make sure to keep
+// Beware, this is duplicated in `libsyntax/entry.rs`, so make sure to keep
 // them in sync.
 fn entry_point_type(item: &Item, at_root: bool) -> EntryPointType {
     match item.node {
@@ -98,7 +98,7 @@ fn entry_point_type(item: &Item, at_root: bool) -> EntryPointType {
                 EntryPointType::MainAttr
             } else if item.name == "main" {
                 if at_root {
-                    // This is a top-level function so can be 'main'
+                    // This is a top-level function so can be 'main'.
                     EntryPointType::MainNamed
                 } else {
                     EntryPointType::OtherMain

src/librustc/middle/expr_use_visitor.rs

@@ -813,7 +813,7 @@ impl<'a, 'gcx, 'tcx> ExprUseVisitor<'a, 'gcx, 'tcx> {
         self.consume_expr(&arm.body);
     }
 
-    /// Walks a pat that occurs in isolation (i.e. top-level of fn
+    /// Walks a pat that occurs in isolation (i.e., top-level of fn
     /// arg or let binding.  *Not* a match arm or nested pat.)
     fn walk_irrefutable_pat(&mut self, cmt_discr: mc::cmt<'tcx>, pat: &hir::Pat) {
         let mut mode = Unknown;
@@ -851,7 +851,7 @@ impl<'a, 'gcx, 'tcx> ExprUseVisitor<'a, 'gcx, 'tcx> {
     }
 
     /// The core driver for walking a pattern; `match_mode` must be
-    /// established up front, e.g. via `determine_pat_move_mode` (see
+    /// established up front, e.g., via `determine_pat_move_mode` (see
     /// also `walk_irrefutable_pat` for patterns that stand alone).
     fn walk_pat(&mut self, cmt_discr: mc::cmt<'tcx>, pat: &hir::Pat, match_mode: MatchMode) {
         debug!("walk_pat(cmt_discr={:?}, pat={:?})", cmt_discr, pat);

src/librustc/middle/lang_items.rs

@@ -13,9 +13,9 @@
 // Language items are items that represent concepts intrinsic to the language
 // itself. Examples are:
 //
-// * Traits that specify "kinds"; e.g. "Sync", "Send".
+// * Traits that specify "kinds"; e.g., "Sync", "Send".
 //
-// * Traits that represent operators; e.g. "Add", "Sub", "Index".
+// * Traits that represent operators; e.g., "Add", "Sub", "Index".
 //
 // * Functions called by the compiler itself.
 

src/librustc/middle/lib_features.rs

@@ -8,9 +8,9 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-// Detecting lib features (i.e. features that are not lang features).
+// Detecting lib features (i.e., features that are not lang features).
 //
-// These are declared using stability attributes (e.g. `#[stable (..)]`
+// These are declared using stability attributes (e.g., `#[stable (..)]`
 // and `#[unstable (..)]`), but are not declared in one single location
 // (unlike lang features), which means we need to collect them instead.
 
@@ -61,7 +61,7 @@ impl<'a, 'tcx> LibFeatureCollector<'a, 'tcx> {
     fn extract(&self, attr: &Attribute) -> Option<(Symbol, Option<Symbol>, Span)> {
         let stab_attrs = vec!["stable", "unstable", "rustc_const_unstable"];
 
-        // Find a stability attribute (i.e. `#[stable (..)]`, `#[unstable (..)]`,
+        // Find a stability attribute (i.e., `#[stable (..)]`, `#[unstable (..)]`,
         // `#[rustc_const_unstable (..)]`).
         if let Some(stab_attr) = stab_attrs.iter().find(|stab_attr| {
             attr.check_name(stab_attr)

src/librustc/middle/liveness.rs

@@ -554,7 +554,7 @@ struct RWUTable {
     /// 65 bits of data into 32; in the uncommon cases, it expands the 65 bits
     /// in 96.
     ///
-    /// More compact representations are possible -- e.g. use only 2 bits per
+    /// More compact representations are possible -- e.g., use only 2 bits per
     /// packed `RWU` and make the secondary table a HashMap that maps from
     /// indices to `RWU`s -- but this one strikes a good balance between size
     /// and speed.

src/librustc/middle/mem_categorization.rs

@@ -127,7 +127,7 @@ pub enum PointerKind<'tcx> {
 }
 
 // We use the term "interior" to mean "something reachable from the
-// base without a pointer dereference", e.g. a field
+// base without a pointer dereference", e.g., a field
 #[derive(Clone, Copy, PartialEq, Eq, Hash)]
 pub enum InteriorKind {
     InteriorField(FieldIndex),
@@ -153,8 +153,8 @@ impl Hash for FieldIndex {
 
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub enum InteriorOffsetKind {
-    Index,   // e.g. `array_expr[index_expr]`
+    Index,   // e.g., `array_expr[index_expr]`
-    Pattern, // e.g. `fn foo([_, a, _, _]: [A; 4]) { ... }`
+    Pattern, // e.g., `fn foo([_, a, _, _]: [A; 4]) { ... }`
 }
 
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
@@ -961,7 +961,7 @@ impl<'a, 'gcx, 'tcx> MemCategorizationContext<'a, 'gcx, 'tcx> {
 
         debug!("cat_rvalue_node: promotable = {:?}", promotable);
 
-        // Always promote `[T; 0]` (even when e.g. borrowed mutably).
+        // Always promote `[T; 0]` (even when e.g., borrowed mutably).
         let promotable = match expr_ty.sty {
             ty::Array(_, len) if len.assert_usize(self.tcx) == Some(0) => true,
             _ => promotable,

src/librustc/middle/region.rs

@@ -84,7 +84,7 @@ use rustc_data_structures::stable_hasher::{HashStable, StableHasher,
 ///  (D9.): DestructionScope for temporaries created during M8.
 /// (R10.): Remainder scope for block `'b:`, stmt 1 (let y = ...).
 /// (D11.): DestructionScope for temporaries and bindings from block `'b:`.
-/// (D12.): DestructionScope for temporaries created during M1 (e.g. f()).
+/// (D12.): DestructionScope for temporaries created during M1 (e.g., f()).
 /// ```
 ///
 /// Note that while the above picture shows the destruction scopes
@@ -155,7 +155,7 @@ pub enum ScopeData {
 ///   everything after that first `let`. (If you want a scope that
 ///   includes EXPR_1 as well, then do not use `Scope::Remainder`,
 ///   but instead another `Scope` that encompasses the whole block,
-///   e.g. `Scope::Node`.
+///   e.g., `Scope::Node`.
 ///
 /// * the subscope with `first_statement_index == 1` is scope of `c`,
 ///   and thus does not include EXPR_2, but covers the `...`.
@@ -172,7 +172,7 @@ static_assert!(ASSERT_SCOPE_DATA: mem::size_of::<ScopeData>() == 4);
 impl Scope {
     /// Returns a item-local id associated with this scope.
     ///
-    /// NB: likely to be replaced as API is refined; e.g. pnkfelix
+    /// N.B., likely to be replaced as API is refined; e.g., pnkfelix
     /// anticipates `fn entry_node_id` and `fn each_exit_node_id`.
     pub fn item_local_id(&self) -> hir::ItemLocalId {
         self.id
@@ -770,10 +770,10 @@ fn resolve_block<'a, 'tcx>(visitor: &mut RegionResolutionVisitor<'a, 'tcx>, blk:
     //    }, other_argument());
     //
     // Each of the statements within the block is a terminating
-    // scope, and thus a temporary (e.g. the result of calling
+    // scope, and thus a temporary (e.g., the result of calling
     // `bar()` in the initializer expression for `let inner = ...;`)
     // will be cleaned up immediately after its corresponding
-    // statement (i.e. `let inner = ...;`) executes.
+    // statement (i.e., `let inner = ...;`) executes.
     //
     // On the other hand, temporaries associated with evaluating the
     // tail expression for the block are assigned lifetimes so that
@@ -984,7 +984,7 @@ fn resolve_local<'a, 'tcx>(visitor: &mut RegionResolutionVisitor<'a, 'tcx>,
 
     // As an exception to the normal rules governing temporary
     // lifetimes, initializers in a let have a temporary lifetime
-    // of the enclosing block. This means that e.g. a program
+    // of the enclosing block. This means that e.g., a program
     // like the following is legal:
     //
     //     let ref x = HashMap::new();
@@ -1183,7 +1183,7 @@ fn resolve_local<'a, 'tcx>(visitor: &mut RegionResolutionVisitor<'a, 'tcx>,
         loop {
             // Note: give all the expressions matching `ET` with the
             // extended temporary lifetime, not just the innermost rvalue,
-            // because in codegen if we must compile e.g. `*rvalue()`
+            // because in codegen if we must compile e.g., `*rvalue()`
             // into a temporary, we request the temporary scope of the
             // outer expression.
             visitor.scope_tree.record_rvalue_scope(expr.hir_id.local_id, blk_scope);
@@ -1281,7 +1281,7 @@ impl<'a, 'tcx> Visitor<'tcx> for RegionResolutionVisitor<'a, 'tcx> {
             // according to rvalue lifetime semantics, using the same
             // syntactical rules used for let initializers.
             //
-            // E.g. in `let x = &f();`, the temporary holding the result from
+            // e.g., in `let x = &f();`, the temporary holding the result from
             // the `f()` call lives for the entirety of the surrounding block.
             //
             // Similarly, `const X: ... = &f();` would have the result of `f()`
@@ -1292,7 +1292,7 @@ impl<'a, 'tcx> Visitor<'tcx> for RegionResolutionVisitor<'a, 'tcx> {
             //
             // However, `const Y: ... = g(&f());`, like `let y = g(&f());`,
             // would *not* let the `f()` temporary escape into an outer scope
-            // (i.e. `'static`), which means that after `g` returns, it drops,
+            // (i.e., `'static`), which means that after `g` returns, it drops,
             // and all the associated destruction scope rules apply.
             self.cx.var_parent = None;
             resolve_local(self, None, Some(&body.value));

src/librustc/middle/resolve_lifetime.rs

@@ -303,14 +303,14 @@ enum Scope<'a> {
     /// Lifetimes introduced by a fn are scoped to the call-site for that fn,
     /// if this is a fn body, otherwise the original definitions are used.
     /// Unspecified lifetimes are inferred, unless an elision scope is nested,
-    /// e.g. `(&T, fn(&T) -> &T);` becomes `(&'_ T, for<'a> fn(&'a T) -> &'a T)`.
+    /// e.g., `(&T, fn(&T) -> &T);` becomes `(&'_ T, for<'a> fn(&'a T) -> &'a T)`.
     Body {
         id: hir::BodyId,
         s: ScopeRef<'a>,
     },
 
     /// A scope which either determines unspecified lifetimes or errors
-    /// on them (e.g. due to ambiguity). For more details, see `Elide`.
+    /// on them (e.g., due to ambiguity). For more details, see `Elide`.
     Elision {
         elide: Elide,
         s: ScopeRef<'a>,
@@ -622,13 +622,13 @@ impl<'a, 'tcx> Visitor<'tcx> for LifetimeContext<'a, 'tcx> {
                     LifetimeName::Implicit => {
                         // If the user does not write *anything*, we
                         // use the object lifetime defaulting
-                        // rules. So e.g. `Box<dyn Debug>` becomes
+                        // rules. So e.g., `Box<dyn Debug>` becomes
                         // `Box<dyn Debug + 'static>`.
                         self.resolve_object_lifetime_default(lifetime)
                     }
                     LifetimeName::Underscore => {
                         // If the user writes `'_`, we use the *ordinary* elision
-                        // rules. So the `'_` in e.g. `Box<dyn Debug + '_>` will be
+                        // rules. So the `'_` in e.g., `Box<dyn Debug + '_>` will be
                         // resolved the same as the `'_` in `&'_ Foo`.
                         //
                         // cc #48468
@@ -1699,7 +1699,7 @@ impl<'a, 'tcx> LifetimeContext<'a, 'tcx> {
     {
         insert_late_bound_lifetimes(self.map, decl, generics);
 
-        // Find the start of nested early scopes, e.g. in methods.
+        // Find the start of nested early scopes, e.g., in methods.
         let mut index = 0;
         if let Some(parent_id) = parent_id {
             let parent = self.tcx.hir().expect_item(parent_id);