Auto merge of #58341 - alexreg:cosmetic-2-doc-comments, r=steveklabnik

Cosmetic improvements to doc comments

This has been factored out from https://github.com/rust-lang/rust/pull/58036 to only include changes to documentation comments (throughout the rustc codebase).

r? @steveklabnik

Once you're happy with this, maybe we could get it through with r=1, so it doesn't constantly get invalidated? (I'm not sure this will be an issue, but just in case...) Anyway, thanks for your advice so far!

src/bootstrap/builder.rs

@@ -60,17 +60,17 @@ pub trait Step: 'static + Clone + Debug + PartialEq + Eq + Hash {
     /// Run this rule for all hosts without cross compiling.
     const ONLY_HOSTS: bool = false;
 
-    /// Primary function to execute this rule. Can call `builder.ensure(...)`
+    /// Primary function to execute this rule. Can call `builder.ensure()`
     /// with other steps to run those.
     fn run(self, builder: &Builder) -> Self::Output;
 
     /// When bootstrap is passed a set of paths, this controls whether this rule
     /// will execute. However, it does not get called in a "default" context
-    /// when we are not passed any paths; in that case, make_run is called
+    /// when we are not passed any paths; in that case, `make_run` is called
     /// directly.
     fn should_run(run: ShouldRun) -> ShouldRun;
 
-    /// Build up a "root" rule, either as a default rule or from a path passed
+    /// Builds up a "root" rule, either as a default rule or from a path passed
     /// to us.
     ///
     /// When path is `None`, we are executing in a context where no paths were
@@ -648,7 +648,7 @@ impl<'a> Builder<'a> {
         add_lib_path(vec![self.rustc_libdir(compiler)], cmd);
     }
 
-    /// Get a path to the compiler specified.
+    /// Gets a path to the compiler specified.
     pub fn rustc(&self, compiler: Compiler) -> PathBuf {
         if compiler.is_snapshot(self) {
             self.initial_rustc.clone()
@@ -659,7 +659,7 @@ impl<'a> Builder<'a> {
         }
     }
 
-    /// Get the paths to all of the compiler's codegen backends.
+    /// Gets the paths to all of the compiler's codegen backends.
     fn codegen_backends(&self, compiler: Compiler) -> impl Iterator<Item = PathBuf> {
         fs::read_dir(self.sysroot_codegen_backends(compiler))
             .into_iter()

src/bootstrap/cache.rs

@@ -227,10 +227,10 @@ lazy_static! {
     pub static ref INTERNER: Interner = Interner::default();
 }
 
-/// This is essentially a HashMap which allows storing any type in its input and
+/// This is essentially a `HashMap` which allows storing any type in its input and
 /// any type in its output. It is a write-once cache; values are never evicted,
 /// which means that references to the value can safely be returned from the
-/// get() method.
+/// `get()` method.
 #[derive(Debug)]
 pub struct Cache(
     RefCell<HashMap<

src/bootstrap/check.rs

@@ -66,7 +66,7 @@ impl Step for Rustc {
         });
     }
 
-    /// Build the compiler.
+    /// Builds the compiler.
     ///
     /// This will build the compiler for a particular stage of the build using
     /// the `compiler` targeting the `target` architecture. The artifacts

src/bootstrap/clean.rs

@@ -3,7 +3,7 @@
 //! Responsible for cleaning out a build directory of all old and stale
 //! artifacts to prepare for a fresh build. Currently doesn't remove the
 //! `build/cache` directory (download cache) or the `build/$target/llvm`
-//! directory unless the --all flag is present.
+//! directory unless the `--all` flag is present.
 
 use std::fs;
 use std::io::{self, ErrorKind};

src/bootstrap/compile.rs

@@ -48,7 +48,7 @@ impl Step for Std {
         });
     }
 
-    /// Build the standard library.
+    /// Builds the standard library.
     ///
     /// This will build the standard library for a particular stage of the build
     /// using the `compiler` targeting the `target` architecture. The artifacts
@@ -269,7 +269,7 @@ impl Step for StartupObjects {
         });
     }
 
-    /// Build and prepare startup objects like rsbegin.o and rsend.o
+    /// Builds and prepare startup objects like rsbegin.o and rsend.o
     ///
     /// These are primarily used on Windows right now for linking executables/dlls.
     /// They don't require any library support as they're just plain old object
@@ -334,7 +334,7 @@ impl Step for Test {
         });
     }
 
-    /// Build libtest.
+    /// Builds libtest.
     ///
     /// This will build libtest and supporting libraries for a particular stage of
     /// the build using the `compiler` targeting the `target` architecture. The
@@ -455,7 +455,7 @@ impl Step for Rustc {
         });
     }
 
-    /// Build the compiler.
+    /// Builds the compiler.
     ///
     /// This will build the compiler for a particular stage of the build using
     /// the `compiler` targeting the `target` architecture. The artifacts

src/bootstrap/dist.rs

@@ -342,7 +342,7 @@ impl Step for Mingw {
         run.builder.ensure(Mingw { host: run.target });
     }
 
-    /// Build the `rust-mingw` installer component.
+    /// Builds 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).

src/bootstrap/doc.rs

@@ -259,7 +259,7 @@ impl Step for TheBook {
         });
     }
 
-    /// Build the book and associated stuff.
+    /// Builds the book and associated stuff.
     ///
     /// We need to build:
     ///
@@ -611,7 +611,7 @@ impl Step for WhitelistedRustc {
         });
     }
 
-    /// Generate whitelisted compiler crate documentation.
+    /// Generates whitelisted compiler crate documentation.
     ///
     /// This will generate all documentation for crates that are whitelisted
     /// to be included in the standard documentation. This documentation is
@@ -683,7 +683,7 @@ impl Step for Rustc {
         });
     }
 
-    /// Generate compiler documentation.
+    /// Generates compiler documentation.
     ///
     /// This will generate all documentation for compiler and dependencies.
     /// Compiler documentation is distributed separately, so we make sure
@@ -784,7 +784,7 @@ impl Step for Rustdoc {
         });
     }
 
-    /// Generate compiler documentation.
+    /// Generates compiler documentation.
     ///
     /// This will generate all documentation for compiler and dependencies.
     /// Compiler documentation is distributed separately, so we make sure

src/bootstrap/lib.rs

@@ -69,7 +69,7 @@
 //! ## Copying stage0 {std,test,rustc}
 //!
 //! This copies the build output from Cargo into
-//! `build/$HOST/stage0-sysroot/lib/rustlib/$ARCH/lib`. FIXME: This step's
+//! `build/$HOST/stage0-sysroot/lib/rustlib/$ARCH/lib`. FIXME: this step's
 //! documentation should be expanded -- the information already here may be
 //! incorrect.
 //!
@@ -504,7 +504,7 @@ impl Build {
         cleared
     }
 
-    /// Get the space-separated set of activated features for the standard
+    /// Gets the space-separated set of activated features for the standard
     /// library.
     fn std_features(&self) -> String {
         let mut features = "panic-unwind".to_string();
@@ -521,7 +521,7 @@ impl Build {
         features
     }
 
-    /// Get the space-separated set of activated features for the compiler.
+    /// Gets the space-separated set of activated features for the compiler.
     fn rustc_features(&self) -> String {
         let mut features = String::new();
         if self.config.jemalloc {
@@ -609,7 +609,7 @@ impl Build {
         self.out.join(&*target).join("crate-docs")
     }
 
-    /// Returns true if no custom `llvm-config` is set for the specified target.
+    /// Returns `true` if no custom `llvm-config` is set for the specified target.
     ///
     /// If no custom `llvm-config` was specified then Rust's llvm will be used.
     fn is_rust_llvm(&self, target: Interned<String>) -> bool {
@@ -857,13 +857,13 @@ impl Build {
             .map(|p| &**p)
     }
 
-    /// Returns true if this is a no-std `target`, if defined
+    /// Returns `true` if this is a no-std `target`, if defined
     fn no_std(&self, target: Interned<String>) -> Option<bool> {
         self.config.target_config.get(&target)
             .map(|t| t.no_std)
     }
 
-    /// Returns whether the target will be tested using the `remote-test-client`
+    /// Returns `true` if the target will be tested using the `remote-test-client`
     /// and `remote-test-server` binaries.
     fn remote_tested(&self, target: Interned<String>) -> bool {
         self.qemu_rootfs(target).is_some() || target.contains("android") ||
@@ -1059,7 +1059,7 @@ impl Build {
         self.rust_info.version(self, channel::CFG_RELEASE_NUM)
     }
 
-    /// Return the full commit hash
+    /// Returns the full commit hash.
     fn rust_sha(&self) -> Option<&str> {
         self.rust_info.sha()
     }
@@ -1079,7 +1079,7 @@ impl Build {
         panic!("failed to find version in {}'s Cargo.toml", package)
     }
 
-    /// Returns whether unstable features should be enabled for the compiler
+    /// Returns `true` if unstable features should be enabled for the compiler
     /// we're building.
     fn unstable_features(&self) -> bool {
         match &self.config.channel[..] {
@@ -1327,7 +1327,7 @@ impl<'a> Compiler {
         self
     }
 
-    /// Returns whether this is a snapshot compiler for `build`'s configuration
+    /// Returns `true` if this is a snapshot compiler for `build`'s configuration
     pub fn is_snapshot(&self, build: &Build) -> bool {
         self.stage == 0 && self.host == build.build
     }

src/bootstrap/test.rs

@@ -30,9 +30,9 @@ const ADB_TEST_DIR: &str = "/data/tmp/work";
 /// The two modes of the test runner; tests or benchmarks.
 #[derive(Debug, PartialEq, Eq, Hash, Copy, Clone, PartialOrd, Ord)]
 pub enum TestKind {
-    /// Run `cargo test`
+    /// Run `cargo test`.
     Test,
-    /// Run `cargo bench`
+    /// Run `cargo bench`.
     Bench,
 }
 
@@ -1288,7 +1288,7 @@ impl Step for DocTest {
         run.never()
     }
 
-    /// Run `rustdoc --test` for all documentation in `src/doc`.
+    /// Runs `rustdoc --test` for all documentation in `src/doc`.
     ///
     /// 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
@@ -1408,7 +1408,7 @@ impl Step for ErrorIndex {
         });
     }
 
-    /// Run the error index generator tool to execute the tests located in the error
+    /// Runs the error index generator tool to execute the tests located in the error
     /// index.
     ///
     /// The `error_index_generator` tool lives in `src/tools` and is used to
@@ -1614,7 +1614,7 @@ impl Step for Crate {
         }
     }
 
-    /// Run all unit tests plus documentation tests for a given crate defined
+    /// Runs all unit tests plus documentation tests for a given crate defined
     /// by a `Cargo.toml` (single manifest)
     ///
     /// This is what runs tests for crates like the standard library, compiler, etc.
@@ -1833,7 +1833,7 @@ fn envify(s: &str) -> String {
 /// the standard library and such to the emulator ahead of time. This step
 /// represents this and is a dependency of all test suites.
 ///
-/// Most of the time this is a noop. For some steps such as shipping data to
+/// Most of the time this is a no-op. For some steps such as shipping data to
 /// QEMU we have to build our own tools so we've got conditional dependencies
 /// on those programs as well. Note that the remote test client is built for
 /// the build target (us) and the server is built for the target.
@@ -1904,7 +1904,7 @@ impl Step for Distcheck {
         run.builder.ensure(Distcheck);
     }
 
-    /// Run "distcheck", a 'make check' from a tarball
+    /// Runs "distcheck", a 'make check' from a tarball
     fn run(self, builder: &Builder) {
         builder.info("Distcheck");
         let dir = builder.out.join("tmp").join("distcheck");
@@ -1965,7 +1965,7 @@ impl Step for Bootstrap {
     const DEFAULT: bool = true;
     const ONLY_HOSTS: bool = true;
 
-    /// Test the build system itself
+    /// Tests the build system itself.
     fn run(self, builder: &Builder) {
         let mut cmd = Command::new(&builder.initial_cargo);
         cmd.arg("test")

src/bootstrap/tool.rs

@@ -40,7 +40,7 @@ impl Step for ToolBuild {
         run.never()
     }
 
-    /// Build a tool in `src/tools`
+    /// Builds a tool in `src/tools`
     ///
     /// This will build the specified tool with the specified `host` compiler in
     /// `stage` into the normal cargo output directory.
@@ -621,7 +621,7 @@ tool_extended!((self, builder),
 );
 
 impl<'a> Builder<'a> {
-    /// Get a `Command` which is ready to run `tool` in `stage` built for
+    /// Gets a `Command` which is ready to run `tool` in `stage` built for
     /// `host`.
     pub fn tool_cmd(&self, tool: Tool) -> Command {
         let mut cmd = Command::new(self.tool_exe(tool));

src/bootstrap/util.rs

@@ -33,7 +33,7 @@ pub fn exe(name: &str, target: &str) -> String {
     }
 }
 
-/// Returns whether the file name given looks like a dynamic library.
+/// Returns `true` if the file name given looks like a dynamic library.
 pub fn is_dylib(name: &str) -> bool {
     name.ends_with(".dylib") || name.ends_with(".so") || name.ends_with(".dll")
 }

src/build_helper/lib.rs

@@ -163,7 +163,7 @@ pub fn mtime(path: &Path) -> SystemTime {
         .unwrap_or(UNIX_EPOCH)
 }
 
-/// Returns whether `dst` is up to date given that the file or files in `src`
+/// Returns `true` if `dst` is up to date given that the file or files in `src`
 /// are used to generate it.
 ///
 /// Uses last-modified time checks to verify this.
@@ -190,12 +190,12 @@ pub struct NativeLibBoilerplate {
 }
 
 impl NativeLibBoilerplate {
-    /// On OSX we don't want to ship the exact filename that compiler-rt builds.
+    /// On macOS we don't want to ship the exact filename that compiler-rt builds.
     /// This conflicts with the system and ours is likely a wildly different
     /// version, so they can't be substituted.
     ///
     /// As a result, we rename it here but we need to also use
-    /// `install_name_tool` on OSX to rename the commands listed inside of it to
+    /// `install_name_tool` on macOS to rename the commands listed inside of it to
     /// ensure it's linked against correctly.
     pub fn fixup_sanitizer_lib_name(&self, sanitizer_name: &str) {
         if env::var("TARGET").unwrap() != "x86_64-apple-darwin" {

src/liballoc/collections/binary_heap.rs

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

src/liballoc/collections/btree/map.rs

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

src/liballoc/collections/btree/node.rs

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

src/liballoc/collections/btree/set.rs

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

src/liballoc/collections/vec_deque.rs

@@ -124,7 +124,7 @@ impl<T> VecDeque<T> {
         ptr::write(self.ptr().add(off), value);
     }
 
-    /// Returns `true` if and only if the buffer is at full capacity.
+    /// Returns `true` if the buffer is at full capacity.
     #[inline]
     fn is_full(&self) -> bool {
         self.cap() - self.len() == 1
@@ -560,7 +560,7 @@ impl<T> VecDeque<T> {
     /// Does nothing if the capacity is already sufficient.
     ///
     /// Note that the allocator may give the collection more space than it
-    /// requests. Therefore capacity can not be relied upon to be precisely
+    /// requests. Therefore, capacity can not be relied upon to be precisely
     /// minimal. Prefer `reserve` if future insertions are expected.
     ///
     /// # Errors
@@ -924,7 +924,7 @@ impl<T> VecDeque<T> {
         self.tail == self.head
     }
 
-    /// Create a draining iterator that removes the specified range in the
+    /// Creates a draining iterator that removes the specified range in the
     /// `VecDeque` and yields the removed items.
     ///
     /// Note 1: The element range is removed even if the iterator is not
@@ -932,7 +932,7 @@ impl<T> VecDeque<T> {
     ///
     /// Note 2: It is unspecified how many elements are removed from the deque,
     /// if the `Drain` value is not dropped, but the borrow it holds expires
-    /// (eg. due to mem::forget).
+    /// (e.g., due to `mem::forget`).
     ///
     /// # Panics
     ///

src/liballoc/macros.rs

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

src/liballoc/raw_vec.rs

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

src/liballoc/rc.rs

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

src/liballoc/slice.rs

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

src/liballoc/string.rs

@@ -963,7 +963,7 @@ impl String {
     /// Does nothing if the capacity is already sufficient.
     ///
     /// Note that the allocator may give the collection more space than it
-    /// requests. Therefore capacity can not be relied upon to be precisely
+    /// requests. Therefore, capacity can not be relied upon to be precisely
     /// minimal. Prefer `reserve` if future insertions are expected.
     ///
     /// # Errors
@@ -1377,9 +1377,7 @@ impl String {
         self.vec.len()
     }
 
-    /// Returns `true` if this `String` has a length of zero.
+    /// Returns `true` if this `String` has a length of zero, and `false` otherwise.
-    ///
-    /// Returns `false` otherwise.
     ///
     /// # Examples
     ///

src/liballoc/sync.rs

@@ -560,7 +560,7 @@ impl<T: ?Sized> Arc<T> {
 
     #[inline]
     #[stable(feature = "ptr_eq", since = "1.17.0")]
-    /// Returns true if the two `Arc`s point to the same value (not
+    /// Returns `true` if the two `Arc`s point to the same value (not
     /// just values that compare as equal).
     ///
     /// # Examples
@@ -1191,8 +1191,8 @@ impl<T: ?Sized> Weak<T> {
         })
     }
 
-    /// Return `None` when the pointer is dangling and there is no allocated `ArcInner`,
+    /// Returns `None` when the pointer is dangling and there is no allocated `ArcInner`,
-    /// i.e., this `Weak` was created by `Weak::new`
+    /// (i.e., when this `Weak` was created by `Weak::new`).
     #[inline]
     fn inner(&self) -> Option<&ArcInner<T>> {
         if is_dangling(self.ptr) {
@@ -1202,7 +1202,7 @@ impl<T: ?Sized> Weak<T> {
         }
     }
 
-    /// Returns true if the two `Weak`s point to the same value (not just values
+    /// Returns `true` if the two `Weak`s point to the same value (not just values
     /// that compare as equal).
     ///
     /// # Notes

src/liballoc/tests/heap.rs

@@ -2,7 +2,7 @@
 
 use std::alloc::{Global, Alloc, Layout, System};
 
-/// https://github.com/rust-lang/rust/issues/45955
+/// Issue #45955.
 #[test]
 fn alloc_system_overaligned_request() {
     check_overalign_requests(System)

src/liballoc/vec.rs

@@ -463,7 +463,7 @@ impl<T> Vec<T> {
     /// Does nothing if the capacity is already sufficient.
     ///
     /// Note that the allocator may give the collection more space than it
-    /// requests. Therefore capacity can not be relied upon to be precisely
+    /// requests. Therefore, capacity can not be relied upon to be precisely
     /// minimal. Prefer `reserve` if future insertions are expected.
     ///
     /// # Panics
@@ -525,7 +525,7 @@ impl<T> Vec<T> {
     /// Does nothing if the capacity is already sufficient.
     ///
     /// Note that the allocator may give the collection more space than it
-    /// requests. Therefore capacity can not be relied upon to be precisely
+    /// requests. Therefore, capacity can not be relied upon to be precisely
     /// minimal. Prefer `reserve` if future insertions are expected.
     ///
     /// # Errors
@@ -2608,7 +2608,7 @@ impl<T> Drain<'_, T> {
     /// The range from `self.vec.len` to `self.tail_start` contains elements
     /// that have been moved out.
     /// Fill that range as much as possible with new elements from the `replace_with` iterator.
-    /// Return whether we filled the entire range. (`replace_with.next()` didn’t return `None`.)
+    /// Returns `true` if we filled the entire range. (`replace_with.next()` didn’t return `None`.)
     unsafe fn fill<I: Iterator<Item=T>>(&mut self, replace_with: &mut I) -> bool {
         let vec = self.vec.as_mut();
         let range_start = vec.len;
@@ -2628,7 +2628,7 @@ impl<T> Drain<'_, T> {
         true
     }
 
-    /// Make room for inserting more elements before the tail.
+    /// Makes room for inserting more elements before the tail.
     unsafe fn move_tail(&mut self, extra_capacity: usize) {
         let vec = self.vec.as_mut();
         let used_capacity = self.tail_start + self.tail_len;

src/libcore/any.rs

@@ -31,8 +31,8 @@
 //! fn log<T: Any + Debug>(value: &T) {
 //!     let value_any = value as &dyn Any;
 //!
-//!     // try to convert our value to a String.  If successful, we want to
+//!     // Try to convert our value to a `String`. If successful, we want to
-//!     // output the String's length as well as its value.  If not, it's a
+//!     // output the String`'s length as well as its value. If not, it's a
 //!     // different type: just print it out unadorned.
 //!     match value_any.downcast_ref::<String>() {
 //!         Some(as_string) => {

src/libcore/cell.rs

@@ -130,7 +130,7 @@
 //!
 //! This is simply a special - but common - case of the previous: hiding mutability for operations
 //! that appear to be immutable. The `clone` method is expected to not change the source value, and
-//! is declared to take `&self`, not `&mut self`. Therefore any mutation that happens in the
+//! is declared to take `&self`, not `&mut self`. Therefore, any mutation that happens in the
 //! `clone` method must use cell types. For example, `Rc<T>` maintains its reference counts within a
 //! `Cell<T>`.
 //!
@@ -1145,7 +1145,7 @@ impl<'b, T: ?Sized> Ref<'b, T> {
         }
     }
 
-    /// Make a new `Ref` for a component of the borrowed data.
+    /// Makes a new `Ref` for a component of the borrowed data.
     ///
     /// The `RefCell` is already immutably borrowed, so this cannot fail.
     ///
@@ -1174,7 +1174,7 @@ impl<'b, T: ?Sized> Ref<'b, T> {
         }
     }
 
-    /// Split a `Ref` into multiple `Ref`s for different components of the
+    /// Splits a `Ref` into multiple `Ref`s for different components of the
     /// borrowed data.
     ///
     /// The `RefCell` is already immutably borrowed, so this cannot fail.
@@ -1217,7 +1217,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
+    /// Makes 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.
@@ -1253,7 +1253,7 @@ impl<'b, T: ?Sized> RefMut<'b, T> {
         }
     }
 
-    /// Split a `RefMut` into multiple `RefMut`s for different components of the
+    /// Splits a `RefMut` into multiple `RefMut`s for different components of the
     /// borrowed data.
     ///
     /// The underlying `RefCell` will remain mutably borrowed until both
@@ -1416,7 +1416,7 @@ impl<T: ?Sized + fmt::Display> fmt::Display for RefMut<'_, T> {
 /// co-exist with it. A `&mut T` must always be unique.
 ///
 /// Note that while mutating or mutably aliasing the contents of an `&UnsafeCell<T>` is
-/// okay (provided you enforce the invariants some other way), it is still undefined behavior
+/// ok (provided you enforce the invariants some other way), it is still undefined behavior
 /// to have multiple `&mut UnsafeCell<T>` aliases.
 ///
 /// # Examples

src/libcore/char/decode.rs

@@ -20,7 +20,7 @@ pub struct DecodeUtf16Error {
     code: u16,
 }
 
-/// Create an iterator over the UTF-16 encoded code points in `iter`,
+/// Creates an iterator over the UTF-16 encoded code points in `iter`,
 /// returning unpaired surrogates as `Err`s.
 ///
 /// # Examples

src/libcore/char/methods.rs

@@ -524,7 +524,7 @@ impl char {
         }
     }
 
-    /// Returns true if this `char` is an alphabetic code point, and false if not.
+    /// Returns `true` if this `char` is an alphabetic code point, and false if not.
     ///
     /// # Examples
     ///
@@ -548,7 +548,7 @@ impl char {
         }
     }
 
-    /// Returns true if this `char` satisfies the 'XID_Start' Unicode property, and false
+    /// Returns `true` if this `char` satisfies the 'XID_Start' Unicode property, and false
     /// otherwise.
     ///
     /// 'XID_Start' is a Unicode Derived Property specified in
@@ -562,7 +562,7 @@ impl char {
         derived_property::XID_Start(self)
     }
 
-    /// Returns true if this `char` satisfies the 'XID_Continue' Unicode property, and false
+    /// Returns `true` if this `char` satisfies the 'XID_Continue' Unicode property, and false
     /// otherwise.
     ///
     /// 'XID_Continue' is a Unicode Derived Property specified in
@@ -576,7 +576,7 @@ impl char {
         derived_property::XID_Continue(self)
     }
 
-    /// Returns true if this `char` is lowercase, and false otherwise.
+    /// Returns `true` if this `char` is lowercase.
     ///
     /// 'Lowercase' is defined according to the terms of the Unicode Derived Core
     /// Property `Lowercase`.
@@ -604,7 +604,7 @@ impl char {
         }
     }
 
-    /// Returns true if this `char` is uppercase, and false otherwise.
+    /// Returns `true` if this `char` is uppercase.
     ///
     /// 'Uppercase' is defined according to the terms of the Unicode Derived Core
     /// Property `Uppercase`.
@@ -632,7 +632,7 @@ impl char {
         }
     }
 
-    /// Returns true if this `char` is whitespace, and false otherwise.
+    /// Returns `true` if this `char` is whitespace.
     ///
     /// 'Whitespace' is defined according to the terms of the Unicode Derived Core
     /// Property `White_Space`.
@@ -659,7 +659,7 @@ impl char {
         }
     }
 
-    /// Returns true if this `char` is alphanumeric, and false otherwise.
+    /// Returns `true` if this `char` is alphanumeric.
     ///
     /// 'Alphanumeric'-ness is defined in terms of the Unicode General Categories
     /// 'Nd', 'Nl', 'No' and the Derived Core Property 'Alphabetic'.
@@ -684,7 +684,7 @@ impl char {
         self.is_alphabetic() || self.is_numeric()
     }
 
-    /// Returns true if this `char` is a control code point, and false otherwise.
+    /// Returns `true` if this `char` is a control code point.
     ///
     /// 'Control code point' is defined in terms of the Unicode General
     /// Category `Cc`.
@@ -704,7 +704,7 @@ impl char {
         general_category::Cc(self)
     }
 
-    /// Returns true if this `char` is an extended grapheme character, and false otherwise.
+    /// Returns `true` if this `char` is an extended grapheme character.
     ///
     /// 'Extended grapheme character' is defined in terms of the Unicode Shaping and Rendering
     /// Category `Grapheme_Extend`.
@@ -713,7 +713,7 @@ impl char {
         derived_property::Grapheme_Extend(self)
     }
 
-    /// Returns true if this `char` is numeric, and false otherwise.
+    /// Returns `true` if this `char` is numeric.
     ///
     /// 'Numeric'-ness is defined in terms of the Unicode General Categories
     /// 'Nd', 'Nl', 'No'.

src/libcore/default.rs

@@ -54,7 +54,7 @@
 ///
 /// ## How can I implement `Default`?
 ///
-/// Provide an implementation for the `default()` method that returns the value of
+/// Provides an implementation for the `default()` method that returns the value of
 /// your type that should be the default:
 ///
 /// ```

src/libcore/ffi.rs

@@ -184,7 +184,7 @@ impl<'a> VaList<'a> {
         va_arg(self)
     }
 
-    /// Copy the `va_list` at the current location.
+    /// Copies the `va_list` at the current location.
     #[unstable(feature = "c_variadic",
                reason = "the `c_variadic` feature has not been properly tested on \
                          all supported platforms",
@@ -213,7 +213,7 @@ extern "rust-intrinsic" {
     /// `va_copy`.
     fn va_end(ap: &mut VaList);
 
-    /// Copy the current location of arglist `src` to the arglist `dst`.
+    /// Copies the current location of arglist `src` to the arglist `dst`.
     #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"),
                   not(target_arch = "x86_64")),
               windows))]

src/libcore/fmt/mod.rs

@@ -483,12 +483,12 @@ impl Display for Arguments<'_> {
 /// implementations, such as [`debug_struct`][debug_struct].
 ///
 /// `Debug` implementations using either `derive` or the debug builder API
-/// on [`Formatter`] support pretty printing using the alternate flag: `{:#?}`.
+/// on [`Formatter`] support pretty-printing using the alternate flag: `{:#?}`.
 ///
 /// [debug_struct]: ../../std/fmt/struct.Formatter.html#method.debug_struct
 /// [`Formatter`]: ../../std/fmt/struct.Formatter.html
 ///
-/// Pretty printing with `#?`:
+/// Pretty-printing with `#?`:
 ///
 /// ```
 /// #[derive(Debug)]

src/libcore/hash/sip.rs

@@ -10,7 +10,7 @@ use mem;
 /// An implementation of SipHash 1-3.
 ///
 /// This is currently the default hashing function used by standard library
-/// (eg. `collections::HashMap` uses it by default).
+/// (e.g., `collections::HashMap` uses it by default).
 ///
 /// See: <https://131002.net/siphash>
 #[unstable(feature = "hashmap_internals", issue = "0")]
@@ -90,7 +90,7 @@ macro_rules! compress {
     });
 }
 
-/// Load an integer of the desired type from a byte stream, in LE order. Uses
+/// Loads an integer of the desired type from a byte stream, in LE order. Uses
 /// `copy_nonoverlapping` to let the compiler generate the most efficient way
 /// to load it from a possibly unaligned address.
 ///
@@ -107,7 +107,7 @@ macro_rules! load_int_le {
     });
 }
 
-/// Load an u64 using up to 7 bytes of a byte slice.
+/// Loads an u64 using up to 7 bytes of a byte slice.
 ///
 /// Unsafe because: unchecked indexing at start..start+len
 #[inline]

src/libcore/hint.rs

@@ -34,7 +34,7 @@ use intrinsics;
 ///     use std::hint::unreachable_unchecked;
 ///
 ///     // `b.saturating_add(1)` is always positive (not zero),
-///     // hence `checked_div` will never return None.
+///     // hence `checked_div` will never return `None`.
 ///     // Therefore, the else branch is unreachable.
 ///     a.checked_div(b.saturating_add(1))
 ///         .unwrap_or_else(|| unsafe { unreachable_unchecked() })

src/libcore/intrinsics.rs

@@ -1,6 +1,6 @@
-//! rustc compiler intrinsics.
+//! Compiler intrinsics.
 //!
-//! The corresponding definitions are in librustc_codegen_llvm/intrinsic.rs.
+//! The corresponding definitions are in `librustc_codegen_llvm/intrinsic.rs`.
 //!
 //! # Volatiles
 //!
@@ -315,35 +315,35 @@ extern "rust-intrinsic" {
     /// [`AtomicBool::swap`](../../std/sync/atomic/struct.AtomicBool.html#method.swap).
     pub fn atomic_xchg_relaxed<T>(dst: *mut T, src: T) -> T;
 
-    /// Add to the current value, returning the previous value.
+    /// Adds to the current value, returning the previous value.
     /// The stabilized version of this intrinsic is available on the
     /// `std::sync::atomic` types via the `fetch_add` method by passing
     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
     /// as the `order`. For example,
     /// [`AtomicIsize::fetch_add`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_add).
     pub fn atomic_xadd<T>(dst: *mut T, src: T) -> T;
-    /// Add to the current value, returning the previous value.
+    /// Adds to the current value, returning the previous value.
     /// The stabilized version of this intrinsic is available on the
     /// `std::sync::atomic` types via the `fetch_add` method by passing
     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
     /// as the `order`. For example,
     /// [`AtomicIsize::fetch_add`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_add).
     pub fn atomic_xadd_acq<T>(dst: *mut T, src: T) -> T;
-    /// Add to the current value, returning the previous value.
+    /// Adds to the current value, returning the previous value.
     /// The stabilized version of this intrinsic is available on the
     /// `std::sync::atomic` types via the `fetch_add` method by passing
     /// [`Ordering::Release`](../../std/sync/atomic/enum.Ordering.html)
     /// as the `order`. For example,
     /// [`AtomicIsize::fetch_add`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_add).
     pub fn atomic_xadd_rel<T>(dst: *mut T, src: T) -> T;
-    /// Add to the current value, returning the previous value.
+    /// Adds to the current value, returning the previous value.
     /// The stabilized version of this intrinsic is available on the
     /// `std::sync::atomic` types via the `fetch_add` method by passing
     /// [`Ordering::AcqRel`](../../std/sync/atomic/enum.Ordering.html)
     /// as the `order`. For example,
     /// [`AtomicIsize::fetch_add`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_add).
     pub fn atomic_xadd_acqrel<T>(dst: *mut T, src: T) -> T;
-    /// Add to the current value, returning the previous value.
+    /// Adds to the current value, returning the previous value.
     /// The stabilized version of this intrinsic is available on the
     /// `std::sync::atomic` types via the `fetch_add` method by passing
     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
@@ -556,7 +556,7 @@ extern "rust-intrinsic" {
     pub fn atomic_umax_relaxed<T>(dst: *mut T, src: T) -> T;
 
     /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
-    /// if supported; otherwise, it is a noop.
+    /// if supported; otherwise, it is a no-op.
     /// Prefetches have no effect on the behavior of the program but can change its performance
     /// characteristics.
     ///
@@ -564,7 +564,7 @@ extern "rust-intrinsic" {
     /// ranging from (0) - no locality, to (3) - extremely local keep in cache
     pub fn prefetch_read_data<T>(data: *const T, locality: i32);
     /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
-    /// if supported; otherwise, it is a noop.
+    /// if supported; otherwise, it is a no-op.
     /// Prefetches have no effect on the behavior of the program but can change its performance
     /// characteristics.
     ///
@@ -572,7 +572,7 @@ extern "rust-intrinsic" {
     /// ranging from (0) - no locality, to (3) - extremely local keep in cache
     pub fn prefetch_write_data<T>(data: *const T, locality: i32);
     /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
-    /// if supported; otherwise, it is a noop.
+    /// if supported; otherwise, it is a no-op.
     /// Prefetches have no effect on the behavior of the program but can change its performance
     /// characteristics.
     ///
@@ -580,7 +580,7 @@ extern "rust-intrinsic" {
     /// ranging from (0) - no locality, to (3) - extremely local keep in cache
     pub fn prefetch_read_instruction<T>(data: *const T, locality: i32);
     /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
-    /// if supported; otherwise, it is a noop.
+    /// if supported; otherwise, it is a no-op.
     /// Prefetches have no effect on the behavior of the program but can change its performance
     /// characteristics.
     ///
@@ -697,7 +697,7 @@ extern "rust-intrinsic" {
     /// Creates a value initialized to zero.
     ///
     /// `init` is unsafe because it returns a zeroed-out datum,
-    /// which is unsafe unless T is `Copy`.  Also, even if T is
+    /// which is unsafe unless `T` is `Copy`. Also, even if T is
     /// `Copy`, an all-zero value may not correspond to any legitimate
     /// state for the type in question.
     pub fn init<T>() -> T;
@@ -857,7 +857,7 @@ extern "rust-intrinsic" {
     ///
     /// // The no-copy, unsafe way, still using transmute, but not UB.
     /// // This is equivalent to the original, but safer, and reuses the
-    /// // same Vec internals. Therefore the new inner type must have the
+    /// // same `Vec` internals. Therefore, the new inner type must have the
     /// // exact same size, and the same alignment, as the old type.
     /// // The same caveats exist for this method as transmute, for
     /// // the original inner type (`&i32`) to the converted inner type
@@ -875,8 +875,8 @@ extern "rust-intrinsic" {
     /// ```
     /// use std::{slice, mem};
     ///
-    /// // There are multiple ways to do this; and there are multiple problems
+    /// // There are multiple ways to do this, and there are multiple problems
-    /// // with the following, transmute, way.
+    /// // with the following (transmute) way.
     /// fn split_at_mut_transmute<T>(slice: &mut [T], mid: usize)
     ///                              -> (&mut [T], &mut [T]) {
     ///     let len = slice.len();
@@ -1200,19 +1200,19 @@ extern "rust-intrinsic" {
     /// unless size is equal to zero.
     pub fn volatile_set_memory<T>(dst: *mut T, val: u8, count: usize);
 
-    /// Perform a volatile load from the `src` pointer.
+    /// Performs a volatile load from the `src` pointer.
     /// The stabilized version of this intrinsic is
     /// [`std::ptr::read_volatile`](../../std/ptr/fn.read_volatile.html).
     pub fn volatile_load<T>(src: *const T) -> T;
-    /// Perform a volatile store to the `dst` pointer.
+    /// Performs a volatile store to the `dst` pointer.
     /// The stabilized version of this intrinsic is
     /// [`std::ptr::write_volatile`](../../std/ptr/fn.write_volatile.html).
     pub fn volatile_store<T>(dst: *mut T, val: T);
 
-    /// Perform a volatile load from the `src` pointer
+    /// Performs a volatile load from the `src` pointer
     /// The pointer is not required to be aligned.
     pub fn unaligned_volatile_load<T>(src: *const T) -> T;
-    /// Perform a volatile store to the `dst` pointer.
+    /// Performs a volatile store to the `dst` pointer.
     /// The pointer is not required to be aligned.
     pub fn unaligned_volatile_store<T>(dst: *mut T, val: T);
 

src/libcore/iter/range.rs

@@ -20,19 +20,19 @@ pub trait Step: Clone + PartialOrd + Sized {
     /// without overflow.
     fn steps_between(start: &Self, end: &Self) -> Option<usize>;
 
-    /// Replaces this step with `1`, returning itself
+    /// Replaces this step with `1`, returning itself.
     fn replace_one(&mut self) -> Self;
 
-    /// Replaces this step with `0`, returning itself
+    /// Replaces this step with `0`, returning itself.
     fn replace_zero(&mut self) -> Self;
 
-    /// Adds one to this step, returning the result
+    /// Adds one to this step, returning the result.
     fn add_one(&self) -> Self;
 
-    /// Subtracts one to this step, returning the result
+    /// Subtracts one to this step, returning the result.
     fn sub_one(&self) -> Self;
 
-    /// Add an usize, returning None on overflow
+    /// Adds a `usize`, returning `None` on overflow.
     fn add_usize(&self, n: usize) -> Option<Self>;
 }
 

src/libcore/iter/traits/exact_size.rs

@@ -104,7 +104,7 @@ pub trait ExactSizeIterator: Iterator {
         lower
     }
 
-    /// Returns whether the iterator is empty.
+    /// Returns `true` if the iterator is empty.
     ///
     /// This method has a default implementation using `self.len()`, so you
     /// don't need to implement it yourself.

src/libcore/iter/traits/iterator.rs

@@ -120,7 +120,7 @@ pub trait Iterator {
     /// // ... and then None once it's over.
     /// assert_eq!(None, iter.next());
     ///
-    /// // More calls may or may not return None. Here, they always will.
+    /// // More calls may or may not return `None`. Here, they always will.
     /// assert_eq!(None, iter.next());
     /// assert_eq!(None, iter.next());
     /// ```
@@ -1215,7 +1215,7 @@ pub trait Iterator {
     /// assert_eq!(iter.next(), Some(4));
     /// assert_eq!(iter.next(), None);
     ///
-    /// // it will always return None after the first time.
+    /// // it will always return `None` after the first time.
     /// assert_eq!(iter.next(), None);
     /// assert_eq!(iter.next(), None);
     /// assert_eq!(iter.next(), None);

src/libcore/macros.rs

@@ -1,4 +1,4 @@
-/// Entry point of thread panic, for details, see std::macros
+/// Entry point of thread panic. For details, see `std::macros`.
 #[macro_export]
 #[cfg_attr(not(stage0), allow_internal_unstable(core_panic, __rust_unstable_column))]
 #[cfg_attr(stage0, allow_internal_unstable)]
@@ -495,7 +495,7 @@ macro_rules! unreachable {
 /// A standardized placeholder for marking unfinished code.
 ///
 /// This can be useful if you are prototyping and are just looking to have your
-/// code typecheck, or if you're implementing a trait that requires multiple
+/// code type-check, or if you're implementing a trait that requires multiple
 /// methods, and you're only planning on using one of them.
 ///
 /// # Panics

src/libcore/mem.rs

@@ -295,7 +295,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
@@ -403,7 +403,7 @@ pub fn align_of_val<T: ?Sized>(val: &T) -> usize {
     unsafe { intrinsics::min_align_of_val(val) }
 }
 
-/// Returns whether dropping values of type `T` matters.
+/// Returns `true` if dropping values of type `T` matters.
 ///
 /// This is purely an optimization hint, and may be implemented conservatively:
 /// it may return `true` for types that don't actually need to be dropped.
@@ -958,7 +958,7 @@ impl<T> ManuallyDrop<T> {
         ManuallyDrop { value }
     }
 
-    /// Extract the value from the `ManuallyDrop` container.
+    /// Extracts the value from the `ManuallyDrop` container.
     ///
     /// This allows the value to be dropped again.
     ///
@@ -1040,24 +1040,27 @@ impl<T: ?Sized> DerefMut for ManuallyDrop<T> {
 /// The compiler, in general, assumes that variables are properly initialized
 /// at their respective type. For example, a variable of reference type must
 /// be aligned and non-NULL. This is an invariant that must *always* be upheld,
-/// even in unsafe code.  As a consequence, 0-initializing a variable of reference
+/// even in unsafe code. As a consequence, zero-initializing a variable of reference
 /// type causes instantaneous undefined behavior, no matter whether that reference
 /// ever gets used to access memory:
+///
 /// ```rust,no_run
 /// use std::mem;
 ///
 /// let x: &i32 = unsafe { mem::zeroed() }; // undefined behavior!
 /// ```
+///
 /// This is exploited by the compiler for various optimizations, such as eliding
 /// run-time checks and optimizing `enum` layout.
 ///
-/// Not initializing memory at all (instead of 0-initializing it) causes the same
+/// Not initializing memory at all (instead of zero--initializing it) causes the same
 /// issue: after all, the initial value of the variable might just happen to be
 /// one that violates the invariant.
 ///
 /// `MaybeUninit` serves to enable unsafe code to deal with uninitialized data:
 /// it is a signal to the compiler indicating that the data here might *not*
 /// be initialized:
+///
 /// ```rust
 /// #![feature(maybe_uninit)]
 /// use std::mem::MaybeUninit;
@@ -1070,6 +1073,7 @@ impl<T: ?Sized> DerefMut for ManuallyDrop<T> {
 /// // initializing `x`!
 /// let x = unsafe { x.into_initialized() };
 /// ```
+///
 /// The compiler then knows to not optimize this code.
 #[allow(missing_debug_implementations)]
 #[unstable(feature = "maybe_uninit", issue = "53491")]
@@ -1090,7 +1094,7 @@ impl<T> MaybeUninit<T> {
         MaybeUninit { value: ManuallyDrop::new(val) }
     }
 
-    /// Create a new `MaybeUninit` in an uninitialized state.
+    /// Creates a new `MaybeUninit` in an uninitialized state.
     ///
     /// Note that dropping a `MaybeUninit` will never call `T`'s drop code.
     /// It is your responsibility to make sure `T` gets dropped if it got initialized.
@@ -1100,7 +1104,7 @@ impl<T> MaybeUninit<T> {
         MaybeUninit { uninit: () }
     }
 
-    /// Create a new `MaybeUninit` in an uninitialized state, with the memory being
+    /// Creates a new `MaybeUninit` in an uninitialized state, with the memory being
     /// filled with `0` bytes. It depends on `T` whether that already makes for
     /// proper initialization. For example, `MaybeUninit<usize>::zeroed()` is initialized,
     /// but `MaybeUninit<&'static i32>::zeroed()` is not because references must not
@@ -1118,9 +1122,9 @@ impl<T> MaybeUninit<T> {
         u
     }
 
-    /// Set the value of the `MaybeUninit`. This overwrites any previous value without dropping it.
+    /// Sets the value of the `MaybeUninit`. This overwrites any previous value without dropping it.
-    /// For your convenience, this also returns a mutable reference to the (now
+    /// For your convenience, this also returns a mutable reference to the (now safely initialized)
-    /// safely initialized) content of `self`.
+    /// contents of `self`.
     #[unstable(feature = "maybe_uninit", issue = "53491")]
     #[inline(always)]
     pub fn set(&mut self, val: T) -> &mut T {
@@ -1130,7 +1134,7 @@ impl<T> MaybeUninit<T> {
         }
     }
 
-    /// Extract the value from the `MaybeUninit` container.  This is a great way
+    /// Extracts the value from the `MaybeUninit` container. This is a great way
     /// to ensure that the data will get dropped, because the resulting `T` is
     /// subject to the usual drop handling.
     ///
@@ -1153,7 +1157,7 @@ impl<T> MaybeUninit<T> {
         self.into_initialized()
     }
 
-    /// Get a reference to the contained value.
+    /// Gets a reference to the contained value.
     ///
     /// # Unsafety
     ///
@@ -1165,7 +1169,7 @@ impl<T> MaybeUninit<T> {
         &*self.value
     }
 
-    /// Get a mutable reference to the contained value.
+    /// Gets a mutable reference to the contained value.
     ///
     /// # Unsafety
     ///
@@ -1180,7 +1184,7 @@ impl<T> MaybeUninit<T> {
         &mut *self.value
     }
 
-    /// Get a pointer to the contained value. Reading from this pointer or turning it
+    /// Gets a pointer to the contained value. Reading from this pointer or turning it
     /// into a reference will be undefined behavior unless the `MaybeUninit` is initialized.
     #[unstable(feature = "maybe_uninit", issue = "53491")]
     #[inline(always)]
@@ -1188,7 +1192,7 @@ impl<T> MaybeUninit<T> {
         unsafe { &*self.value as *const T }
     }
 
-    /// Get a mutable pointer to the contained value. Reading from this pointer or turning it
+    /// Get sa mutable pointer to the contained value. Reading from this pointer or turning it
     /// into a reference will be undefined behavior unless the `MaybeUninit` is initialized.
     #[unstable(feature = "maybe_uninit", issue = "53491")]
     #[inline(always)]
@@ -1196,14 +1200,14 @@ impl<T> MaybeUninit<T> {
         unsafe { &mut *self.value as *mut T }
     }
 
-    /// Get a pointer to the first element of the array.
+    /// Gets a pointer to the first element of the array.
     #[unstable(feature = "maybe_uninit", issue = "53491")]
     #[inline(always)]
     pub fn first_ptr(this: &[MaybeUninit<T>]) -> *const T {
         this as *const [MaybeUninit<T>] as *const T
     }
 
-    /// Get a mutable pointer to the first element of the array.
+    /// Gets a mutable pointer to the first element of the array.
     #[unstable(feature = "maybe_uninit", issue = "53491")]
     #[inline(always)]
     pub fn first_ptr_mut(this: &mut [MaybeUninit<T>]) -> *mut T {

src/libcore/num/dec2flt/algorithm.rs

@@ -61,7 +61,7 @@ mod fpu_precision {
         unsafe { asm!("fldcw $0" :: "m" (cw) :: "volatile") }
     }
 
-    /// Set the precision field of the FPU to `T` and return a `FPUControlWord`
+    /// Sets the precision field of the FPU to `T` and returns a `FPUControlWord`.
     pub fn set_precision<T>() -> FPUControlWord {
         let cw = 0u16;
 

src/libcore/num/dec2flt/mod.rs

@@ -54,7 +54,7 @@
 //! operations as well, if you want 0.5 ULP accuracy you need to do *everything* in full precision
 //! and round *exactly once, at the end*, by considering all truncated bits at once.
 //!
-//! FIXME Although some code duplication is necessary, perhaps parts of the code could be shuffled
+//! FIXME: Although some code duplication is necessary, perhaps parts of the code could be shuffled
 //! around such that less code is duplicated. Large parts of the algorithms are independent of the
 //! float type to output, or only needs access to a few constants, which could be passed in as
 //! parameters.
@@ -209,7 +209,7 @@ fn pfe_invalid() -> ParseFloatError {
     ParseFloatError { kind: FloatErrorKind::Invalid }
 }
 
-/// Split decimal string into sign and the rest, without inspecting or validating the rest.
+/// Splits a decimal string into sign and the rest, without inspecting or validating the rest.
 fn extract_sign(s: &str) -> (Sign, &str) {
     match s.as_bytes()[0] {
         b'+' => (Sign::Positive, &s[1..]),
@@ -219,7 +219,7 @@ fn extract_sign(s: &str) -> (Sign, &str) {
     }
 }
 
-/// Convert a decimal string into a floating point number.
+/// Converts a decimal string into a floating point number.
 fn dec2flt<T: RawFloat>(s: &str) -> Result<T, ParseFloatError> {
     if s.is_empty() {
         return Err(pfe_empty())

src/libcore/num/dec2flt/num.rs

@@ -27,7 +27,7 @@ pub fn compare_with_half_ulp(f: &Big, ones_place: usize) -> Ordering {
     Equal
 }
 
-/// Convert an ASCII string containing only decimal digits to a `u64`.
+/// Converts an ASCII string containing only decimal digits to a `u64`.
 ///
 /// Does not perform checks for overflow or invalid characters, so if the caller is not careful,
 /// the result is bogus and can panic (though it won't be `unsafe`). Additionally, empty strings
@@ -44,7 +44,7 @@ pub fn from_str_unchecked<'a, T>(bytes: T) -> u64 where T : IntoIterator<Item=&'
     result
 }
 
-/// Convert a string of ASCII digits into a bignum.
+/// Converts a string of ASCII digits into a bignum.
 ///
 /// Like `from_str_unchecked`, this function relies on the parser to weed out non-digits.
 pub fn digits_to_big(integral: &[u8], fractional: &[u8]) -> Big {
@@ -69,7 +69,7 @@ pub fn to_u64(x: &Big) -> u64 {
 }
 
 
-/// Extract a range of bits.
+/// Extracts a range of bits.
 
 /// Index 0 is the least significant bit and the range is half-open as usual.
 /// Panics if asked to extract more bits than fit into the return type.

src/libcore/num/dec2flt/parse.rs

@@ -42,7 +42,7 @@ pub enum ParseResult<'a> {
     Invalid,
 }
 
-/// Check if the input string is a valid floating point number and if so, locate the integral
+/// Checks if the input string is a valid floating point number and if so, locate the integral
 /// part, the fractional part, and the exponent in it. Does not handle signs.
 pub fn parse_decimal(s: &str) -> ParseResult {
     if s.is_empty() {

src/libcore/num/dec2flt/rawfp.rs

@@ -59,10 +59,10 @@ pub trait RawFloat
     /// Type used by `to_bits` and `from_bits`.
     type Bits: Add<Output = Self::Bits> + From<u8> + TryFrom<u64>;
 
-    /// Raw transmutation to integer.
+    /// Performs a raw transmutation to an integer.
     fn to_bits(self) -> Self::Bits;
 
-    /// Raw transmutation from integer.
+    /// Performs a raw transmutation from an integer.
     fn from_bits(v: Self::Bits) -> Self;
 
     /// Returns the category that this number falls into.
@@ -71,14 +71,14 @@ pub trait RawFloat
     /// Returns the mantissa, exponent and sign as integers.
     fn integer_decode(self) -> (u64, i16, i8);
 
-    /// Decode the float.
+    /// Decodes the float.
     fn unpack(self) -> Unpacked;
 
-    /// Cast from a small integer that can be represented exactly.  Panic if the integer can't be
+    /// Casts from a small integer that can be represented exactly. Panic if the integer can't be
     /// represented, the other code in this module makes sure to never let that happen.
     fn from_int(x: u64) -> Self;
 
-    /// Get the value 10<sup>e</sup> from a pre-computed table.
+    /// Gets the value 10<sup>e</sup> from a pre-computed table.
     /// Panics for `e >= CEIL_LOG5_OF_MAX_SIG`.
     fn short_fast_pow10(e: usize) -> Self;
 
@@ -240,7 +240,7 @@ impl RawFloat for f64 {
     fn from_bits(v: Self::Bits) -> Self { Self::from_bits(v) }
 }
 
-/// Convert an Fp to the closest machine float type.
+/// Converts an `Fp` to the closest machine float type.
 /// Does not handle subnormal results.
 pub fn fp_to_float<T: RawFloat>(x: Fp) -> T {
     let x = x.normalize();
@@ -319,7 +319,7 @@ pub fn big_to_fp(f: &Big) -> Fp {
     }
 }
 
-/// Find the largest floating point number strictly smaller than the argument.
+/// Finds the largest floating point number strictly smaller than the argument.
 /// Does not handle subnormals, zero, or exponent underflow.
 pub fn prev_float<T: RawFloat>(x: T) -> T {
     match x.classify() {

src/libcore/num/f32.rs

@@ -144,7 +144,7 @@ pub mod consts {
 #[lang = "f32"]
 #[cfg(not(test))]
 impl f32 {
-    /// Returns `true` if this value is `NaN` and false otherwise.
+    /// Returns `true` if this value is `NaN`.
     ///
     /// ```
     /// use std::f32;
@@ -169,8 +169,8 @@ impl f32 {
         f32::from_bits(self.to_bits() & 0x7fff_ffff)
     }
 
-    /// Returns `true` if this value is positive infinity or negative infinity and
+    /// Returns `true` if this value is positive infinity or negative infinity, and
-    /// false otherwise.
+    /// `false` otherwise.
     ///
     /// ```
     /// use std::f32;
@@ -272,7 +272,7 @@ impl f32 {
         }
     }
 
-    /// Returns `true` if and only if `self` has a positive sign, including `+0.0`, `NaN`s with
+    /// Returns `true` if `self` has a positive sign, including `+0.0`, `NaN`s with
     /// positive sign bit and positive infinity.
     ///
     /// ```
@@ -288,7 +288,7 @@ impl f32 {
         !self.is_sign_negative()
     }
 
-    /// Returns `true` if and only if `self` has a negative sign, including `-0.0`, `NaN`s with
+    /// Returns `true` if `self` has a negative sign, including `-0.0`, `NaN`s with
     /// negative sign bit and negative infinity.
     ///
     /// ```

src/libcore/num/f64.rs

@@ -144,7 +144,7 @@ pub mod consts {
 #[lang = "f64"]
 #[cfg(not(test))]
 impl f64 {
-    /// Returns `true` if this value is `NaN` and false otherwise.
+    /// Returns `true` if this value is `NaN`.
     ///
     /// ```
     /// use std::f64;
@@ -169,8 +169,8 @@ impl f64 {
         f64::from_bits(self.to_bits() & 0x7fff_ffff_ffff_ffff)
     }
 
-    /// Returns `true` if this value is positive infinity or negative infinity and
+    /// Returns `true` if this value is positive infinity or negative infinity, and
-    /// false otherwise.
+    /// `false` otherwise.
     ///
     /// ```
     /// use std::f64;
@@ -272,7 +272,7 @@ impl f64 {
         }
     }
 
-    /// Returns `true` if and only if `self` has a positive sign, including `+0.0`, `NaN`s with
+    /// Returns `true` if `self` has a positive sign, including `+0.0`, `NaN`s with
     /// positive sign bit and positive infinity.
     ///
     /// ```
@@ -296,7 +296,7 @@ impl f64 {
         self.is_sign_positive()
     }
 
-    /// Returns `true` if and only if `self` has a negative sign, including `-0.0`, `NaN`s with
+    /// Returns `true` if `self` has a negative sign, including `-0.0`, `NaN`s with
     /// negative sign bit and negative infinity.
     ///
     /// ```

src/libcore/num/mod.rs

@@ -52,7 +52,7 @@ assert_eq!(size_of::<Option<core::num::", stringify!($Ty), ">>(), size_of::<", s
             }
 
             impl $Ty {
-                /// Create a non-zero without checking the value.
+                /// Creates a non-zero without checking the value.
                 ///
                 /// # Safety
                 ///
@@ -63,7 +63,7 @@ assert_eq!(size_of::<Option<core::num::", stringify!($Ty), ">>(), size_of::<", s
                     $Ty(n)
                 }
 
-                /// Create a non-zero if the given value is not zero.
+                /// Creates a non-zero if the given value is not zero.
                 #[$stability]
                 #[inline]
                 pub fn new(n: $Int) -> Option<Self> {

src/libcore/option.rs

@@ -214,7 +214,7 @@ impl<T> Option<T> {
     ///
     /// # Examples
     ///
-    /// Convert an `Option<`[`String`]`>` into an `Option<`[`usize`]`>`, preserving the original.
+    /// Converts an `Option<`[`String`]`>` into an `Option<`[`usize`]`>`, preserving the original.
     /// The [`map`] method takes the `self` argument by value, consuming the original,
     /// so this technique uses `as_ref` to first take an `Option` to a reference
     /// to the value inside the original.
@@ -395,7 +395,7 @@ impl<T> Option<T> {
     ///
     /// # Examples
     ///
-    /// Convert an `Option<`[`String`]`>` into an `Option<`[`usize`]`>`, consuming the original:
+    /// Converts an `Option<`[`String`]`>` into an `Option<`[`usize`]`>`, consuming the original:
     ///
     /// [`String`]: ../../std/string/struct.String.html
     /// [`usize`]: ../../std/primitive.usize.html
@@ -963,7 +963,7 @@ impl<T: Default> Option<T> {
     ///
     /// # Examples
     ///
-    /// Convert a string to an integer, turning poorly-formed strings
+    /// Converts a string to an integer, turning poorly-formed strings
     /// into 0 (the default value for integers). [`parse`] converts
     /// a string to any other type that implements [`FromStr`], returning
     /// [`None`] on error.

src/libcore/pin.rs

@@ -199,7 +199,7 @@ impl<P: Deref> Pin<P> {
         Pin { pointer }
     }
 
-    /// Get a pinned shared reference from this pinned pointer.
+    /// Gets a pinned shared reference from this pinned pointer.
     #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
     pub fn as_ref(self: &Pin<P>) -> Pin<&P::Target> {
@@ -208,7 +208,7 @@ impl<P: Deref> Pin<P> {
 }
 
 impl<P: DerefMut> Pin<P> {
-    /// Get a pinned mutable reference from this pinned pointer.
+    /// Gets a pinned mutable reference from this pinned pointer.
     #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
     pub fn as_mut(self: &mut Pin<P>) -> Pin<&mut P::Target> {
@@ -247,7 +247,7 @@ impl<'a, T: ?Sized> Pin<&'a T> {
         Pin::new_unchecked(new_pointer)
     }
 
-    /// Get a shared reference out of a pin.
+    /// Gets a shared reference out of a pin.
     ///
     /// Note: `Pin` also implements `Deref` to the target, which can be used
     /// to access the inner value. However, `Deref` only provides a reference
@@ -262,14 +262,14 @@ impl<'a, T: ?Sized> Pin<&'a T> {
 }
 
 impl<'a, T: ?Sized> Pin<&'a mut T> {
-    /// Convert this `Pin<&mut T>` into a `Pin<&T>` with the same lifetime.
+    /// Converts this `Pin<&mut T>` into a `Pin<&T>` with the same lifetime.
     #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
     pub fn into_ref(self: Pin<&'a mut T>) -> Pin<&'a T> {
         Pin { pointer: self.pointer }
     }
 
-    /// Get a mutable reference to the data inside of this `Pin`.
+    /// Gets a mutable reference to the data inside of this `Pin`.
     ///
     /// This requires that the data inside this `Pin` is `Unpin`.
     ///
@@ -286,7 +286,7 @@ impl<'a, T: ?Sized> Pin<&'a mut T> {
         self.pointer
     }
 
-    /// Get a mutable reference to the data inside of this `Pin`.
+    /// Gets a mutable reference to the data inside of this `Pin`.
     ///
     /// # Safety
     ///

src/libcore/ptr.rs

@@ -825,7 +825,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 noops
 /// and may be ignored.
 ///
 /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
@@ -903,7 +903,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 noops
 /// and may be ignored.
 ///
 /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
@@ -2473,7 +2473,7 @@ impl<T: ?Sized> PartialEq for *mut T {
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: ?Sized> Eq for *mut T {}
 
-/// Compare raw pointers for equality.
+/// Compares raw pointers for equality.
 ///
 /// This is the same as using the `==` operator, but less generic:
 /// the arguments have to be `*const T` raw pointers,

src/libcore/result.rs

@@ -896,7 +896,7 @@ impl<T: Default, E> Result<T, E> {
     ///
     /// # Examples
     ///
-    /// Convert a string to an integer, turning poorly-formed strings
+    /// Converts a string to an integer, turning poorly-formed strings
     /// into 0 (the default value for integers). [`parse`] converts
     /// a string to any other type that implements [`FromStr`], returning an
     /// [`Err`] on error.

src/libcore/slice/memchr.rs

@@ -11,7 +11,7 @@ const HI_U64: u64 = 0x8080808080808080;
 const LO_USIZE: usize = LO_U64 as usize;
 const HI_USIZE: usize = HI_U64 as usize;
 
-/// Returns whether `x` contains any zero byte.
+/// Returns `true` if `x` contains any zero byte.
 ///
 /// From *Matters Computational*, J. Arndt:
 ///

src/libcore/slice/mod.rs

@@ -3145,7 +3145,7 @@ unsafe impl<T: Sync> Sync for Iter<'_, T> {}
 unsafe impl<T: Sync> Send for Iter<'_, T> {}
 
 impl<'a, T> Iter<'a, T> {
-    /// View the underlying data as a subslice of the original data.
+    /// Views the underlying data as a subslice of the original data.
     ///
     /// This has the same lifetime as the original slice, and so the
     /// iterator can continue to be used while this exists.
@@ -3247,7 +3247,7 @@ unsafe impl<T: Sync> Sync for IterMut<'_, T> {}
 unsafe impl<T: Send> Send for IterMut<'_, T> {}
 
 impl<'a, T> IterMut<'a, T> {
-    /// View the underlying data as a subslice of the original data.
+    /// Views the underlying data as a subslice of the original data.
     ///
     /// To avoid creating `&mut` references that alias, this is forced
     /// to consume the iterator.
@@ -4123,7 +4123,7 @@ pub struct ChunksExact<'a, T:'a> {
 }
 
 impl<'a, T> ChunksExact<'a, T> {
-    /// Return the remainder of the original slice that is not going to be
+    /// Returns the remainder of the original slice that is not going to be
     /// returned by the iterator. The returned slice has at most `chunk_size-1`
     /// elements.
     #[stable(feature = "chunks_exact", since = "1.31.0")]
@@ -4247,7 +4247,7 @@ pub struct ChunksExactMut<'a, T:'a> {
 }
 
 impl<'a, T> ChunksExactMut<'a, T> {
-    /// Return the remainder of the original slice that is not going to be
+    /// Returns the remainder of the original slice that is not going to be
     /// returned by the iterator. The returned slice has at most `chunk_size-1`
     /// elements.
     #[stable(feature = "chunks_exact", since = "1.31.0")]
@@ -4619,7 +4619,7 @@ pub struct RChunksExact<'a, T:'a> {
 }
 
 impl<'a, T> RChunksExact<'a, T> {
-    /// Return the remainder of the original slice that is not going to be
+    /// Returns the remainder of the original slice that is not going to be
     /// returned by the iterator. The returned slice has at most `chunk_size-1`
     /// elements.
     #[stable(feature = "rchunks", since = "1.31.0")]
@@ -4744,7 +4744,7 @@ pub struct RChunksExactMut<'a, T:'a> {
 }
 
 impl<'a, T> RChunksExactMut<'a, T> {
-    /// Return the remainder of the original slice that is not going to be
+    /// Returns the remainder of the original slice that is not going to be
     /// returned by the iterator. The returned slice has at most `chunk_size-1`
     /// elements.
     #[stable(feature = "rchunks", since = "1.31.0")]

src/libcore/str/mod.rs

@@ -1,6 +1,6 @@
-//! String manipulation
+//! String manipulation.
 //!
-//! For more details, see std::str
+//! For more details, see the `std::str` module.
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
@@ -226,7 +226,7 @@ impl Utf8Error {
     #[stable(feature = "utf8_error", since = "1.5.0")]
     pub fn valid_up_to(&self) -> usize { self.valid_up_to }
 
-    /// Provide more information about the failure:
+    /// Provides more information about the failure:
     ///
     /// * `None`: the end of the input was reached unexpectedly.
     ///   `self.valid_up_to()` is 1 to 3 bytes from the end of the input.
@@ -612,7 +612,7 @@ impl<'a> DoubleEndedIterator for Chars<'a> {
 impl FusedIterator for Chars<'_> {}
 
 impl<'a> Chars<'a> {
-    /// View the underlying data as a subslice of the original data.
+    /// Views the underlying data as a subslice of the original data.
     ///
     /// This has the same lifetime as the original slice, and so the
     /// iterator can continue to be used while this exists.
@@ -702,7 +702,7 @@ impl<'a> DoubleEndedIterator for CharIndices<'a> {
 impl FusedIterator for CharIndices<'_> {}
 
 impl<'a> CharIndices<'a> {
-    /// View the underlying data as a subslice of the original data.
+    /// Views the underlying data as a subslice of the original data.
     ///
     /// This has the same lifetime as the original slice, and so the
     /// iterator can continue to be used while this exists.
@@ -2643,7 +2643,7 @@ impl str {
         Bytes(self.as_bytes().iter().cloned())
     }
 
-    /// Split a string slice by whitespace.
+    /// Splits a string slice by whitespace.
     ///
     /// The iterator returned will return string slices that are sub-slices of
     /// the original string slice, separated by any amount of whitespace.
@@ -2686,7 +2686,7 @@ impl str {
         SplitWhitespace { inner: self.split(IsWhitespace).filter(IsNotEmpty) }
     }
 
-    /// Split a string slice by ASCII whitespace.
+    /// Splits a string slice by ASCII whitespace.
     ///
     /// The iterator returned will return string slices that are sub-slices of
     /// the original string slice, separated by any amount of ASCII whitespace.
@@ -3504,7 +3504,7 @@ impl str {
     ///
     /// A string is a sequence of bytes. `start` in this context means the first
     /// position of that byte string; for a left-to-right language like English or
-    /// Russian, this will be left side; and for right-to-left languages like
+    /// Russian, this will be left side, and for right-to-left languages like
     /// like Arabic or Hebrew, this will be the right side.
     ///
     /// # Examples
@@ -3541,7 +3541,7 @@ impl str {
     ///
     /// A string is a sequence of bytes. `end` in this context means the last
     /// position of that byte string; for a left-to-right language like English or
-    /// Russian, this will be right side; and for right-to-left languages like
+    /// Russian, this will be right side, and for right-to-left languages like
     /// like Arabic or Hebrew, this will be the left side.
     ///
     /// # Examples
@@ -3787,7 +3787,7 @@ impl str {
     ///
     /// A string is a sequence of bytes. `start` in this context means the first
     /// position of that byte string; for a left-to-right language like English or
-    /// Russian, this will be left side; and for right-to-left languages like
+    /// Russian, this will be left side, and for right-to-left languages like
     /// like Arabic or Hebrew, this will be the right side.
     ///
     /// # Examples
@@ -3819,7 +3819,7 @@ impl str {
     ///
     /// A string is a sequence of bytes. `end` in this context means the last
     /// position of that byte string; for a left-to-right language like English or
-    /// Russian, this will be right side; and for right-to-left languages like
+    /// Russian, this will be right side, and for right-to-left languages like
     /// like Arabic or Hebrew, this will be the left side.
     ///
     /// # Examples

src/libcore/str/pattern.rs

@@ -1,7 +1,7 @@
 //! The string Pattern API.
 //!
-//! For more details, see the traits `Pattern`, `Searcher`,
+//! For more details, see the traits [`Pattern`], [`Searcher`],
-//! `ReverseSearcher` and `DoubleEndedSearcher`.
+//! [`ReverseSearcher`], and [`DoubleEndedSearcher`].
 
 #![unstable(feature = "pattern",
             reason = "API not fully fleshed out and ready to be stabilized",
@@ -117,7 +117,7 @@ pub unsafe trait Searcher<'a> {
     /// `[Reject(0, 1), Reject(1, 2), Match(2, 5), Reject(5, 8)]`
     fn next(&mut self) -> SearchStep;
 
-    /// Find the next `Match` result. See `next()`
+    /// Finds the next `Match` result. See `next()`
     ///
     /// Unlike next(), there is no guarantee that the returned ranges
     /// of this and next_reject will overlap. This will return (start_match, end_match),
@@ -134,7 +134,7 @@ pub unsafe trait Searcher<'a> {
         }
     }
 
-    /// Find the next `Reject` result. See `next()` and `next_match()`
+    /// Finds the next `Reject` result. See `next()` and `next_match()`
     ///
     /// Unlike next(), there is no guarantee that the returned ranges
     /// of this and next_match will overlap.
@@ -185,7 +185,7 @@ pub unsafe trait ReverseSearcher<'a>: Searcher<'a> {
     /// `[Reject(7, 8), Match(4, 7), Reject(1, 4), Reject(0, 1)]`
     fn next_back(&mut self) -> SearchStep;
 
-    /// Find the next `Match` result. See `next_back()`
+    /// Finds the next `Match` result. See `next_back()`
     #[inline]
     fn next_match_back(&mut self) -> Option<(usize, usize)>{
         loop {
@@ -197,7 +197,7 @@ pub unsafe trait ReverseSearcher<'a>: Searcher<'a> {
         }
     }
 
-    /// Find the next `Reject` result. See `next_back()`
+    /// Finds the next `Reject` result. See `next_back()`
     #[inline]
     fn next_reject_back(&mut self) -> Option<(usize, usize)>{
         loop {

src/libcore/task/poll.rs

@@ -22,7 +22,7 @@ pub enum Poll<T> {
 }
 
 impl<T> Poll<T> {
-    /// Change the ready value of this `Poll` with the closure provided
+    /// Changes the ready value of this `Poll` with the closure provided.
     pub fn map<U, F>(self, f: F) -> Poll<U>
         where F: FnOnce(T) -> U
     {
@@ -32,7 +32,7 @@ impl<T> Poll<T> {
         }
     }
 
-    /// Returns whether this is `Poll::Ready`
+    /// Returns `true` if this is `Poll::Ready`
     #[inline]
     pub fn is_ready(&self) -> bool {
         match *self {
@@ -41,7 +41,7 @@ impl<T> Poll<T> {
         }
     }
 
-    /// Returns whether this is `Poll::Pending`
+    /// Returns `true` if this is `Poll::Pending`
     #[inline]
     pub fn is_pending(&self) -> bool {
         !self.is_ready()
@@ -49,7 +49,7 @@ impl<T> Poll<T> {
 }
 
 impl<T, E> Poll<Result<T, E>> {
-    /// Change the success value of this `Poll` with the closure provided
+    /// Changes the success value of this `Poll` with the closure provided.
     pub fn map_ok<U, F>(self, f: F) -> Poll<Result<U, E>>
         where F: FnOnce(T) -> U
     {
@@ -60,7 +60,7 @@ impl<T, E> Poll<Result<T, E>> {
         }
     }
 
-    /// Change the error value of this `Poll` with the closure provided
+    /// Changes the error value of this `Poll` with the closure provided.
     pub fn map_err<U, F>(self, f: F) -> Poll<Result<T, U>>
         where F: FnOnce(E) -> U
     {

src/libcore/task/wake.rs

@@ -41,11 +41,11 @@ impl Waker {
         unsafe { self.inner.as_ref().wake() }
     }
 
-    /// Returns whether or not this `Waker` and `other` awaken the same task.
+    /// Returns `true` if or not this `Waker` and `other` awaken the same task.
     ///
     /// This function works on a best-effort basis, and may return false even
     /// when the `Waker`s would awaken the same task. However, if this function
-    /// returns true, it is guaranteed that the `Waker`s will awaken the same
+    /// returns `true`, it is guaranteed that the `Waker`s will awaken the same
     /// task.
     ///
     /// This function is primarily used for optimization purposes.
@@ -54,7 +54,7 @@ impl Waker {
         self.inner == other.inner
     }
 
-    /// Returns whether or not this `Waker` and `other` `LocalWaker` awaken
+    /// Returns `true` if or not this `Waker` and `other` `LocalWaker` awaken
     /// the same task.
     ///
     /// This function works on a best-effort basis, and may return false even
@@ -150,7 +150,7 @@ impl LocalWaker {
         unsafe { self.0.inner.as_ref().wake_local() }
     }
 
-    /// Returns whether or not this `LocalWaker` and `other` `LocalWaker` awaken the same task.
+    /// Returns `true` if or not this `LocalWaker` and `other` `LocalWaker` awaken the same task.
     ///
     /// This function works on a best-effort basis, and may return false even
     /// when the `LocalWaker`s would awaken the same task. However, if this function
@@ -163,7 +163,7 @@ impl LocalWaker {
         self.0.will_wake(&other.0)
     }
 
-    /// Returns whether or not this `LocalWaker` and `other` `Waker` awaken the same task.
+    /// Returns `true` if or not this `LocalWaker` and `other` `Waker` awaken the same task.
     ///
     /// This function works on a best-effort basis, and may return false even
     /// when the `Waker`s would awaken the same task. However, if this function
@@ -223,14 +223,14 @@ pub unsafe trait UnsafeWake: Send + Sync {
     /// Drops this instance of `UnsafeWake`, deallocating resources
     /// associated with it.
     ///
-    /// FIXME(cramertj)
+    // FIXME(cramertj):
     /// This method is intended to have a signature such as:
     ///
     /// ```ignore (not-a-doctest)
     /// fn drop_raw(self: *mut Self);
     /// ```
     ///
-    /// Unfortunately in Rust today that signature is not object safe.
+    /// Unfortunately, in Rust today that signature is not object safe.
     /// Nevertheless it's recommended to implement this function *as if* that
     /// were its signature. As such it is not safe to call on an invalid
     /// pointer, nor is the validity of the pointer guaranteed after this

src/libcore/tests/iter.rs

@@ -881,7 +881,7 @@ fn test_iterator_flat_map() {
     assert_eq!(i, ys.len());
 }
 
-/// Test `FlatMap::fold` with items already picked off the front and back,
+/// Tests `FlatMap::fold` with items already picked off the front and back,
 /// to make sure all parts of the `FlatMap` are folded correctly.
 #[test]
 fn test_iterator_flat_map_fold() {
@@ -919,7 +919,7 @@ fn test_iterator_flatten() {
     assert_eq!(i, ys.len());
 }
 
-/// Test `Flatten::fold` with items already picked off the front and back,
+/// Tests `Flatten::fold` with items already picked off the front and back,
 /// to make sure all parts of the `Flatten` are folded correctly.
 #[test]
 fn test_iterator_flatten_fold() {

src/libcore/time.rs

@@ -515,7 +515,7 @@ impl Duration {
         }
     }
 
-    /// Multiply `Duration` by `f64`.
+    /// Multiplies `Duration` by `f64`.
     ///
     /// # Panics
     /// This method will panic if result is not finite, negative or overflows `Duration`.

src/libpanic_unwind/dummy.rs

@@ -1,6 +1,6 @@
-//! Unwinding for wasm32
+//! Unwinding for *wasm32* target.
 //!
-//! Right now we don't support this, so this is just stubs
+//! Right now we don't support this, so this is just stubs.
 
 use alloc::boxed::Box;
 use core::any::Any;

src/libpanic_unwind/dwarf/eh.rs

@@ -6,7 +6,7 @@
 //!   http://www.airs.com/blog/archives/464
 //!
 //! A reference implementation may be found in the GCC source tree
-//! (<root>/libgcc/unwind-c.c as of this writing)
+//! (`<root>/libgcc/unwind-c.c` as of this writing).
 
 #![allow(non_upper_case_globals)]
 #![allow(unused)]

src/libpanic_unwind/dwarf/mod.rs

@@ -1,5 +1,5 @@
 //! Utilities for parsing DWARF-encoded data streams.
-//! See http://www.dwarfstd.org,
+//! See <http://www.dwarfstd.org>,
 //! DWARF-4 standard, Section 7 - "Data Representation"
 
 // This module is used only by x86_64-pc-windows-gnu for now, but we

src/libpanic_unwind/emcc.rs

@@ -1,9 +1,9 @@
-//! Unwinding for emscripten
+//! Unwinding for *emscripten* target.
 //!
 //! Whereas Rust's usual unwinding implementation for Unix platforms
-//! calls into the libunwind APIs directly, on emscripten we instead
+//! calls into the libunwind APIs directly, on Emscripten we instead
 //! call into the C++ unwinding APIs. This is just an expedience since
-//! emscripten's runtime always implements those APIs and does not
+//! Emscripten's runtime always implements those APIs and does not
 //! implement libunwind.
 
 #![allow(private_no_mangle_fns)]

src/libpanic_unwind/gcc.rs

@@ -1,4 +1,4 @@
-//! Implementation of panics backed by libgcc/libunwind (in some form)
+//! Implementation of panics backed by libgcc/libunwind (in some form).
 //!
 //! For background on exception handling and stack unwinding please see
 //! "Exception Handling in LLVM" (llvm.org/docs/ExceptionHandling.html) and

src/libproc_macro/bridge/scoped_cell.rs

@@ -38,7 +38,7 @@ impl<T: LambdaL> ScopedCell<T> {
         ScopedCell(Cell::new(value))
     }
 
-    /// Set the value in `self` to `replacement` while
+    /// Sets the value in `self` to `replacement` while
     /// running `f`, which gets the old value, mutably.
     /// The old value will be restored after `f` exits, even
     /// by panic, including modifications made to it by `f`.
@@ -73,7 +73,7 @@ impl<T: LambdaL> ScopedCell<T> {
         f(RefMutL(put_back_on_drop.value.as_mut().unwrap()))
     }
 
-    /// Set the value in `self` to `value` while running `f`.
+    /// Sets the value in `self` to `value` while running `f`.
     pub fn set<'a, R>(&self, value: <T as ApplyL<'a>>::Out, f: impl FnOnce() -> R) -> R {
         self.replace(value, |_| f())
     }

src/libproc_macro/diagnostic.rs

@@ -56,7 +56,7 @@ pub struct Diagnostic {
 
 macro_rules! diagnostic_child_methods {
     ($spanned:ident, $regular:ident, $level:expr) => (
-        /// Add a new child diagnostic message to `self` with the level
+        /// Adds a new child diagnostic message to `self` with the level
         /// identified by this method's name with the given `spans` and
         /// `message`.
         #[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
@@ -67,7 +67,7 @@ macro_rules! diagnostic_child_methods {
             self
         }
 
-        /// Add a new child diagnostic message to `self` with the level
+        /// Adds a new child diagnostic message to `self` with the level
         /// identified by this method's name with the given `message`.
         #[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
         pub fn $regular<T: Into<String>>(mut self, message: T) -> Diagnostic {
@@ -93,7 +93,7 @@ impl<'a> Iterator for Children<'a> {
 
 #[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
 impl Diagnostic {
-    /// Create a new diagnostic with the given `level` and `message`.
+    /// Creates a new diagnostic with the given `level` and `message`.
     #[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
     pub fn new<T: Into<String>>(level: Level, message: T) -> Diagnostic {
         Diagnostic {
@@ -104,7 +104,7 @@ impl Diagnostic {
         }
     }
 
-    /// Create a new diagnostic with the given `level` and `message` pointing to
+    /// Creates a new diagnostic with the given `level` and `message` pointing to
     /// the given set of `spans`.
     #[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
     pub fn spanned<S, T>(spans: S, level: Level, message: T) -> Diagnostic

src/libproc_macro/lib.rs

@@ -89,7 +89,7 @@ impl TokenStream {
 /// or characters not existing in the language.
 /// All tokens in the parsed stream get `Span::call_site()` spans.
 ///
-/// NOTE: Some errors may cause panics instead of returning `LexError`. We reserve the right to
+/// NOTE: some errors may cause panics instead of returning `LexError`. We reserve the right to
 /// change these errors into `LexError`s later.
 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
 impl FromStr for TokenStream {
@@ -245,7 +245,7 @@ impl !Sync for Span {}
 
 macro_rules! diagnostic_method {
     ($name:ident, $level:expr) => (
-        /// Create a new `Diagnostic` with the given `message` at the span
+        /// Creates a new `Diagnostic` with the given `message` at the span
         /// `self`.
         #[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
         pub fn $name<T: Into<String>>(self, message: T) -> Diagnostic {
@@ -291,19 +291,19 @@ impl Span {
         Span(self.0.source())
     }
 
-    /// Get the starting line/column in the source file for this span.
+    /// Gets the starting line/column in the source file for this span.
     #[unstable(feature = "proc_macro_span", issue = "54725")]
     pub fn start(&self) -> LineColumn {
         self.0.start()
     }
 
-    /// Get the ending line/column in the source file for this span.
+    /// Gets the ending line/column in the source file for this span.
     #[unstable(feature = "proc_macro_span", issue = "54725")]
     pub fn end(&self) -> LineColumn {
         self.0.end()
     }
 
-    /// Create a new span encompassing `self` and `other`.
+    /// Creates a new span encompassing `self` and `other`.
     ///
     /// Returns `None` if `self` and `other` are from different files.
     #[unstable(feature = "proc_macro_span", issue = "54725")]
@@ -369,7 +369,7 @@ impl !Sync for LineColumn {}
 pub struct SourceFile(bridge::client::SourceFile);
 
 impl SourceFile {
-    /// Get the path to this source file.
+    /// Gets the path to this source file.
     ///
     /// ### Note
     /// If the code span associated with this `SourceFile` was generated by an external macro, this

src/librustc/dep_graph/debug.rs

@@ -22,7 +22,7 @@ impl DepNodeFilter {
         }
     }
 
-    /// True if all nodes always pass the filter.
+    /// Returns `true` if all nodes always pass the filter.
     pub fn accepts_all(&self) -> bool {
         self.text.is_empty()
     }

src/librustc/dep_graph/dep_node.rs

@@ -302,7 +302,7 @@ macro_rules! define_dep_nodes {
                 }
             }
 
-            /// Create a new, parameterless DepNode. This method will assert
+            /// Creates a new, parameterless DepNode. This method will assert
             /// that the DepNode corresponding to the given DepKind actually
             /// does not require any parameters.
             #[inline(always)]
@@ -314,7 +314,7 @@ macro_rules! define_dep_nodes {
                 }
             }
 
-            /// Extract the DefId corresponding to this DepNode. This will work
+            /// Extracts the DefId corresponding to this DepNode. This will work
             /// if two conditions are met:
             ///
             /// 1. The Fingerprint of the DepNode actually is a DefPathHash, and
@@ -798,7 +798,7 @@ impl<'a, 'gcx: 'tcx + 'a, 'tcx: 'a> DepNodeParams<'a, 'gcx, 'tcx> for HirId {
 }
 
 /// A "work product" corresponds to a `.o` (or other) file that we
-/// save in between runs. These ids do not have a DefId but rather
+/// save in between runs. These IDs do not have a `DefId` but rather
 /// some independent path or string that persists between runs without
 /// the need to be mapped or unmapped. (This ensures we can serialize
 /// them even in the absence of a tcx.)

src/librustc/dep_graph/dep_tracking_map.rs

@@ -43,7 +43,7 @@ impl<M: DepTrackingMapConfig> MemoizationMap for RefCell<DepTrackingMap<M>> {
     ///
     /// Here, `[op]` represents whatever nodes `op` reads in the
     /// course of execution; `Map(key)` represents the node for this
-    /// map; and `CurrentTask` represents the current task when
+    /// map, and `CurrentTask` represents the current task when
     /// `memoize` is invoked.
     ///
     /// **Important:** when `op` is invoked, the current task will be

src/librustc/dep_graph/graph.rs

@@ -61,13 +61,13 @@ struct DepGraphData {
 
     colors: DepNodeColorMap,
 
-    /// A set of loaded diagnostics which has been emitted.
+    /// A set of loaded diagnostics that have been emitted.
     emitted_diagnostics: Mutex<FxHashSet<DepNodeIndex>>,
 
     /// Used to wait for diagnostics to be emitted.
     emitted_diagnostics_cond_var: Condvar,
 
-    /// When we load, there may be `.o` files, cached mir, or other such
+    /// When we load, there may be `.o` files, cached MIR, or other such
     /// things available to us. If we find that they are not dirty, we
     /// load the path to the file storing those work-products here into
     /// this map. We can later look for and extract that data.
@@ -115,7 +115,7 @@ impl DepGraph {
         }
     }
 
-    /// True if we are actually building the full dep-graph.
+    /// Returns `true` if we are actually building the full dep-graph, and `false` otherwise.
     #[inline]
     pub fn is_fully_enabled(&self) -> bool {
         self.data.is_some()
@@ -320,8 +320,8 @@ impl DepGraph {
         }
     }
 
-    /// Execute something within an "anonymous" task, that is, a task the
+    /// Executes something within an "anonymous" task, that is, a task the
-    /// DepNode of which is determined by the list of inputs it read from.
+    /// `DepNode` of which is determined by the list of inputs it read from.
     pub fn with_anon_task<OP,R>(&self, dep_kind: DepKind, op: OP) -> (R, DepNodeIndex)
         where OP: FnOnce() -> R
     {
@@ -356,8 +356,8 @@ impl DepGraph {
         }
     }
 
-    /// Execute something within an "eval-always" task which is a task
+    /// Executes something within an "eval-always" task which is a task
-    // that runs whenever anything changes.
+    /// that runs whenever anything changes.
     pub fn with_eval_always_task<'a, C, A, R>(
         &self,
         key: DepNode,
@@ -438,7 +438,7 @@ impl DepGraph {
         self.data.as_ref().unwrap().previous.node_to_index(dep_node)
     }
 
-    /// Check whether a previous work product exists for `v` and, if
+    /// Checks whether a previous work product exists for `v` and, if
     /// so, return the path that leads to it. Used to skip doing work.
     pub fn previous_work_product(&self, v: &WorkProductId) -> Option<WorkProduct> {
         self.data
@@ -589,7 +589,7 @@ impl DepGraph {
         }
     }
 
-    /// Try to mark a dep-node which existed in the previous compilation session as green
+    /// Try to mark a dep-node which existed in the previous compilation session as green.
     fn try_mark_previous_green<'tcx>(
         &self,
         tcx: TyCtxt<'_, 'tcx, 'tcx>,
@@ -773,8 +773,8 @@ impl DepGraph {
         Some(dep_node_index)
     }
 
-    /// Atomically emits some loaded diagnotics assuming that this only gets called with
+    /// Atomically emits some loaded diagnotics, assuming that this only gets called with
-    /// did_allocation set to true on one thread
+    /// `did_allocation` set to `true` on a single thread.
     #[cold]
     #[inline(never)]
     fn emit_diagnostics<'tcx>(
@@ -913,7 +913,7 @@ impl DepGraph {
 #[derive(Clone, Debug, RustcEncodable, RustcDecodable)]
 pub struct WorkProduct {
     pub cgu_name: String,
-    /// Saved files associated with this CGU
+    /// Saved files associated with this CGU.
     pub saved_files: Vec<(WorkProductFileKind, String)>,
 }
 
@@ -937,17 +937,17 @@ pub(super) struct CurrentDepGraph {
     #[allow(dead_code)]
     forbidden_edge: Option<EdgeFilter>,
 
-    // Anonymous DepNodes are nodes the ID of which we compute from the list of
+    /// Anonymous `DepNode`s are nodes whose IDs we compute from the list of
-    // their edges. This has the beneficial side-effect that multiple anonymous
+    /// their edges. This has the beneficial side-effect that multiple anonymous
-    // nodes can be coalesced into one without changing the semantics of the
+    /// nodes can be coalesced into one without changing the semantics of the
-    // dependency graph. However, the merging of nodes can lead to a subtle
+    /// dependency graph. However, the merging of nodes can lead to a subtle
-    // problem during red-green marking: The color of an anonymous node from
+    /// problem during red-green marking: The color of an anonymous node from
-    // the current session might "shadow" the color of the node with the same
+    /// the current session might "shadow" the color of the node with the same
-    // ID from the previous session. In order to side-step this problem, we make
+    /// ID from the previous session. In order to side-step this problem, we make
-    // sure that anon-node IDs allocated in different sessions don't overlap.
+    /// sure that anonymous `NodeId`s allocated in different sessions don't overlap.
-    // This is implemented by mixing a session-key into the ID fingerprint of
+    /// This is implemented by mixing a session-key into the ID fingerprint of
-    // each anon node. The session-key is just a random number generated when
+    /// each anon node. The session-key is just a random number generated when
-    // the DepGraph is created.
+    /// the `DepGraph` is created.
     anon_id_seed: Fingerprint,
 
     total_read_count: u64,

src/librustc/hir/check_attr.rs

@@ -91,7 +91,7 @@ struct CheckAttrVisitor<'a, 'tcx: 'a> {
 }
 
 impl<'a, 'tcx> CheckAttrVisitor<'a, 'tcx> {
-    /// Check any attribute.
+    /// Checks any attribute.
     fn check_attributes(&self, item: &hir::Item, target: Target) {
         if target == Target::Fn || target == Target::Const {
             self.tcx.codegen_fn_attrs(self.tcx.hir().local_def_id(item.id));
@@ -115,7 +115,7 @@ impl<'a, 'tcx> CheckAttrVisitor<'a, 'tcx> {
         self.check_used(item, target);
     }
 
-    /// Check if an `#[inline]` is applied to a function or a closure.
+    /// Checks if an `#[inline]` is applied to a function or a closure.
     fn check_inline(&self, attr: &hir::Attribute, span: &Span, target: Target) {
         if target != Target::Fn && target != Target::Closure {
             struct_span_err!(self.tcx.sess,
@@ -127,7 +127,7 @@ impl<'a, 'tcx> CheckAttrVisitor<'a, 'tcx> {
         }
     }
 
-    /// Check if the `#[non_exhaustive]` attribute on an `item` is valid.
+    /// Checks if the `#[non_exhaustive]` attribute on an `item` is valid.
     fn check_non_exhaustive(&self, attr: &hir::Attribute, item: &hir::Item, target: Target) {
         match target {
             Target::Struct | Target::Enum => { /* Valid */ },
@@ -143,7 +143,7 @@ impl<'a, 'tcx> CheckAttrVisitor<'a, 'tcx> {
         }
     }
 
-    /// Check if the `#[marker]` attribute on an `item` is valid.
+    /// Checks if the `#[marker]` attribute on an `item` is valid.
     fn check_marker(&self, attr: &hir::Attribute, item: &hir::Item, target: Target) {
         match target {
             Target::Trait => { /* Valid */ },
@@ -157,7 +157,7 @@ impl<'a, 'tcx> CheckAttrVisitor<'a, 'tcx> {
         }
     }
 
-    /// Check if the `#[repr]` attributes on `item` are valid.
+    /// Checks if the `#[repr]` attributes on `item` are valid.
     fn check_repr(&self, item: &hir::Item, target: Target) {
         // Extract the names of all repr hints, e.g., [foo, bar, align] for:
         // ```

src/librustc/hir/def.rs

@@ -182,7 +182,7 @@ impl<T> ::std::ops::IndexMut<Namespace> for PerNS<T> {
 }
 
 impl<T> PerNS<Option<T>> {
-    /// Returns whether all the items in this collection are `None`.
+    /// Returns `true` if all the items in this collection are `None`.
     pub fn is_empty(&self) -> bool {
         self.type_ns.is_none() && self.value_ns.is_none() && self.macro_ns.is_none()
     }

src/librustc/hir/def_id.rs

@@ -229,7 +229,7 @@ impl fmt::Debug for DefId {
 }
 
 impl DefId {
-    /// Make a local `DefId` with the given index.
+    /// Makes a local `DefId` from the given `DefIndex`.
     #[inline]
     pub fn local(index: DefIndex) -> DefId {
         DefId { krate: LOCAL_CRATE, index: index }

src/librustc/hir/intravisit.rs

@@ -4,7 +4,7 @@
 //! `super::itemlikevisit::ItemLikeVisitor` trait.**
 //!
 //! If you have decided to use this visitor, here are some general
-//! notes on how to do it:
+//! notes on how to do so:
 //!
 //! Each overridden visit method has full control over what
 //! happens with its node, it can do its own traversal of the node's children,
@@ -86,7 +86,7 @@ pub enum NestedVisitorMap<'this, 'tcx: 'this> {
     /// using this setting.
     OnlyBodies(&'this Map<'tcx>),
 
-    /// Visit all nested things, including item-likes.
+    /// Visits all nested things, including item-likes.
     ///
     /// **This is an unusual choice.** It is used when you want to
     /// process everything within their lexical context. Typically you
@@ -96,7 +96,7 @@ pub enum NestedVisitorMap<'this, 'tcx: 'this> {
 
 impl<'this, 'tcx> NestedVisitorMap<'this, 'tcx> {
     /// Returns the map to use for an "intra item-like" thing (if any).
-    /// e.g., function body.
+    /// E.g., function body.
     pub fn intra(self) -> Option<&'this Map<'tcx>> {
         match self {
             NestedVisitorMap::None => None,
@@ -106,7 +106,7 @@ impl<'this, 'tcx> NestedVisitorMap<'this, 'tcx> {
     }
 
     /// Returns the map to use for an "item-like" thing (if any).
-    /// e.g., item, impl-item.
+    /// E.g., item, impl-item.
     pub fn inter(self) -> Option<&'this Map<'tcx>> {
         match self {
             NestedVisitorMap::None => None,
@@ -203,7 +203,7 @@ pub trait Visitor<'v> : Sized {
         }
     }
 
-    /// Visit the top-level item and (optionally) nested items / impl items. See
+    /// Visits the top-level item and (optionally) nested items / impl items. See
     /// `visit_nested_item` for details.
     fn visit_item(&mut self, i: &'v Item) {
         walk_item(self, i)

src/librustc/hir/lowering.rs

@@ -3,24 +3,24 @@
 //! Since the AST and HIR are fairly similar, this is mostly a simple procedure,
 //! much like a fold. Where lowering involves a bit more work things get more
 //! interesting and there are some invariants you should know about. These mostly
-//! concern spans and ids.
+//! concern spans and IDs.
 //!
 //! Spans are assigned to AST nodes during parsing and then are modified during
 //! expansion to indicate the origin of a node and the process it went through
-//! being expanded. Ids are assigned to AST nodes just before lowering.
+//! being expanded. IDs are assigned to AST nodes just before lowering.
 //!
-//! For the simpler lowering steps, ids and spans should be preserved. Unlike
+//! For the simpler lowering steps, IDs and spans should be preserved. Unlike
 //! expansion we do not preserve the process of lowering in the spans, so spans
 //! should not be modified here. When creating a new node (as opposed to
-//! 'folding' an existing one), then you create a new id using `next_id()`.
+//! 'folding' an existing one), then you create a new ID using `next_id()`.
 //!
-//! You must ensure that ids are unique. That means that you should only use the
+//! You must ensure that IDs are unique. That means that you should only use the
-//! id from an AST node in a single HIR node (you can assume that AST node ids
+//! ID from an AST node in a single HIR node (you can assume that AST node IDs
-//! are unique). Every new node must have a unique id. Avoid cloning HIR nodes.
+//! are unique). Every new node must have a unique ID. Avoid cloning HIR nodes.
-//! If you do, you must then set the new node's id to a fresh one.
+//! If you do, you must then set the new node's ID to a fresh one.
 //!
 //! Spans are used for error messages and for tools to map semantics back to
-//! source code. It is therefore not as important with spans as ids to be strict
+//! source code. It is therefore not as important with spans as IDs to be strict
 //! about use (you can't break the compiler by screwing up a span). Obviously, a
 //! HIR node can only have a single span. But multiple nodes can have the same
 //! span and spans don't need to be kept in order, etc. Where code is preserved
@@ -145,7 +145,7 @@ pub trait Resolver {
         is_value: bool,
     ) -> hir::Path;
 
-    /// Obtain the resolution for a node-id.
+    /// Obtain the resolution for a `NodeId`.
     fn get_resolution(&mut self, id: NodeId) -> Option<PathResolution>;
 
     /// Obtain the possible resolutions for the given `use` statement.
@@ -3302,7 +3302,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.)
+    /// `NodeId`s. (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();

src/librustc/hir/map/blocks.rs

@@ -1,5 +1,5 @@
 //! This module provides a simplified abstraction for working with
-//! code blocks identified by their integer node-id.  In particular,
+//! code blocks identified by their integer `NodeId`. In particular,
 //! 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

src/librustc/hir/map/def_collector.rs

@@ -12,7 +12,7 @@ use syntax_pos::Span;
 
 use crate::hir::map::{ITEM_LIKE_SPACE, REGULAR_SPACE};
 
-/// Creates def ids for nodes in the AST.
+/// Creates `DefId`s for nodes in the AST.
 pub struct DefCollector<'a> {
     definitions: &'a mut Definitions,
     parent_def: Option<DefIndex>,

src/librustc/hir/map/definitions.rs

@@ -1,5 +1,5 @@
 //! For each definition, we track the following data. A definition
-//! here is defined somewhat circularly as "something with a def-id",
+//! here is defined somewhat circularly as "something with a `DefId`",
 //! but it generally corresponds to things like structs, enums, etc.
 //! There are also some rather random cases (like const initializer
 //! expressions) that are mostly just leftovers.
@@ -163,10 +163,10 @@ pub struct Definitions {
 /// any) with a `DisambiguatedDefPathData`.
 #[derive(Clone, PartialEq, Debug, Hash, RustcEncodable, RustcDecodable)]
 pub struct DefKey {
-    /// Parent path.
+    /// The parent path.
     pub parent: Option<DefIndex>,
 
-    /// Identifier of this node.
+    /// The identifier of this node.
     pub disambiguated_data: DisambiguatedDefPathData,
 }
 
@@ -207,12 +207,12 @@ impl DefKey {
     }
 }
 
-/// Pair of `DefPathData` and an integer disambiguator. The integer is
+/// A pair of `DefPathData` and an integer disambiguator. The integer is
 /// normally 0, but in the event that there are multiple defs with the
 /// same `parent` and `data`, we use this field to disambiguate
 /// between them. This introduces some artificial ordering dependency
 /// but means that if you have (e.g.) two impls for the same type in
-/// the same module, they do get distinct def-ids.
+/// the same module, they do get distinct `DefId`s.
 #[derive(Clone, PartialEq, Debug, Hash, RustcEncodable, RustcDecodable)]
 pub struct DisambiguatedDefPathData {
     pub data: DefPathData,
@@ -221,10 +221,10 @@ pub struct DisambiguatedDefPathData {
 
 #[derive(Clone, Debug, Hash, RustcEncodable, RustcDecodable)]
 pub struct DefPath {
-    /// the path leading from the crate root to the item
+    /// The path leading from the crate root to the item.
     pub data: Vec<DisambiguatedDefPathData>,
 
-    /// what krate root is this path relative to?
+    /// The crate root this path is relative to.
     pub krate: CrateNum,
 }
 
@@ -260,9 +260,9 @@ impl DefPath {
         DefPath { data: data, krate: krate }
     }
 
-    /// Returns a string representation of the DefPath without
+    /// Returns a string representation of the `DefPath` without
     /// the crate-prefix. This method is useful if you don't have
-    /// a TyCtxt available.
+    /// a `TyCtxt` available.
     pub fn to_string_no_crate(&self) -> String {
         let mut s = String::with_capacity(self.data.len() * 16);
 
@@ -277,7 +277,7 @@ impl DefPath {
         s
     }
 
-    /// Return filename friendly string of the DefPah with the
+    /// Returns a filename-friendly string for the `DefPath`, with the
     /// crate-prefix.
     pub fn to_string_friendly<F>(&self, crate_imported_name: F) -> String
         where F: FnOnce(CrateNum) -> Symbol
@@ -302,9 +302,9 @@ impl DefPath {
         s
     }
 
-    /// Return filename friendly string of the DefPah without
+    /// Returns a filename-friendly string of the `DefPath`, without
     /// the crate-prefix. This method is useful if you don't have
-    /// a TyCtxt available.
+    /// a `TyCtxt` available.
     pub fn to_filename_friendly_no_crate(&self) -> String {
         let mut s = String::with_capacity(self.data.len() * 16);
 
@@ -394,18 +394,18 @@ impl Borrow<Fingerprint> for DefPathHash {
 }
 
 impl Definitions {
-    /// Create new empty definition map.
+    /// Creates new empty definition map.
     ///
-    /// The DefIndex returned from a new Definitions are as follows:
+    /// The `DefIndex` returned from a new `Definitions` are as follows:
-    /// 1. At DefIndexAddressSpace::Low,
+    /// 1. At `DefIndexAddressSpace::Low`,
     ///     CRATE_ROOT has index 0:0, and then new indexes are allocated in
     ///     ascending order.
-    /// 2. At DefIndexAddressSpace::High,
+    /// 2. At `DefIndexAddressSpace::High`,
-    ///     the first FIRST_FREE_HIGH_DEF_INDEX indexes are reserved for
+    ///     the first `FIRST_FREE_HIGH_DEF_INDEX` indexes are reserved for
-    ///     internal use, then 1:FIRST_FREE_HIGH_DEF_INDEX are allocated in
+    ///     internal use, then `1:FIRST_FREE_HIGH_DEF_INDEX` are allocated in
     ///     ascending order.
-    ///
+    //
-    /// FIXME: there is probably a better place to put this comment.
+    // FIXME: there is probably a better place to put this comment.
     pub fn new() -> Self {
         Self::default()
     }
@@ -414,7 +414,7 @@ impl Definitions {
         &self.table
     }
 
-    /// Get the number of definitions.
+    /// Gets the number of definitions.
     pub fn def_index_counts_lo_hi(&self) -> (usize, usize) {
         (self.table.index_to_key[DefIndexAddressSpace::Low.index()].len(),
          self.table.index_to_key[DefIndexAddressSpace::High.index()].len())
@@ -497,8 +497,8 @@ impl Definitions {
         self.node_to_hir_id[node_id]
     }
 
-    /// Retrieve the span of the given `DefId` if `DefId` is in the local crate, the span exists and
+    /// Retrieves the span of the given `DefId` if `DefId` is in the local crate, the span exists
-    /// it's not DUMMY_SP
+    /// and it's not `DUMMY_SP`.
     #[inline]
     pub fn opt_span(&self, def_id: DefId) -> Option<Span> {
         if def_id.krate == LOCAL_CRATE {
@@ -508,7 +508,7 @@ impl Definitions {
         }
     }
 
-    /// Add a definition with a parent definition.
+    /// Adds a root definition (no parent).
     pub fn create_root_def(&mut self,
                            crate_name: &str,
                            crate_disambiguator: CrateDisambiguator)
@@ -606,7 +606,7 @@ impl Definitions {
         index
     }
 
-    /// Initialize the ast::NodeId to HirId mapping once it has been generated during
+    /// Initialize the `ast::NodeId` to `HirId` mapping once it has been generated during
     /// AST to HIR lowering.
     pub fn init_node_id_to_hir_id_mapping(&mut self,
                                           mapping: IndexVec<ast::NodeId, hir::HirId>) {

src/librustc/hir/map/mod.rs

@@ -36,7 +36,7 @@ mod hir_id_validator;
 pub const ITEM_LIKE_SPACE: DefIndexAddressSpace = DefIndexAddressSpace::Low;
 pub const REGULAR_SPACE: DefIndexAddressSpace = DefIndexAddressSpace::High;
 
-/// Represents an entry and its parent NodeId.
+/// Represents an entry and its parent `NodeId`.
 #[derive(Copy, Clone, Debug)]
 pub struct Entry<'hir> {
     parent: NodeId,
@@ -162,8 +162,7 @@ impl Forest {
     }
 }
 
-/// Represents a mapping from Node IDs to AST elements and their parent
+/// Represents a mapping from `NodeId`s to AST elements and their parent `NodeId`s.
-/// Node IDs
 #[derive(Clone)]
 pub struct Map<'hir> {
     /// The backing storage for all the AST nodes.
@@ -473,7 +472,7 @@ impl<'hir> Map<'hir> {
         self.local_def_id(self.body_owner(id))
     }
 
-    /// Given a node id, returns the `BodyId` associated with it,
+    /// Given a `NodeId`, returns the `BodyId` associated with it,
     /// if the node is a body owner, otherwise returns `None`.
     pub fn maybe_body_owned_by(&self, id: NodeId) -> Option<BodyId> {
         if let Some(entry) = self.find_entry(id) {
@@ -558,7 +557,7 @@ impl<'hir> Map<'hir> {
         self.trait_auto_impl(trait_did).is_some()
     }
 
-    /// Get the attributes on the krate. This is preferable to
+    /// Gets the attributes on the crate. This is preferable to
     /// invoking `krate.attrs` because it registers a tighter
     /// dep-graph access.
     pub fn krate_attrs(&self) -> &'hir [ast::Attribute] {
@@ -653,8 +652,7 @@ impl<'hir> Map<'hir> {
         self.get_generics(id).map(|generics| generics.span).filter(|sp| *sp != DUMMY_SP)
     }
 
-    /// Retrieve the Node corresponding to `id`, returning None if
+    /// Retrieves the `Node` corresponding to `id`, returning `None` if cannot be found.
-    /// cannot be found.
     pub fn find(&self, id: NodeId) -> Option<Node<'hir>> {
         let result = self.find_entry(id).and_then(|entry| {
             if let Node::Crate = entry.node {
@@ -683,8 +681,8 @@ impl<'hir> Map<'hir> {
     /// 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`
-    /// from a node to the root of the ast (unless you get the same id back here
+    /// 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).
+    /// 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 {
         if self.dep_graph.is_fully_enabled() {
             let hir_id_owner = self.node_to_hir_id(id).owner;
@@ -725,7 +723,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 `NodeId` 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,
@@ -761,7 +759,7 @@ impl<'hir> Map<'hir> {
         }
     }
 
-    /// Retrieve the `NodeId` for `id`'s enclosing method, unless there's a
+    /// Retrieves 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.
     ///
@@ -809,7 +807,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
+    /// Retrieves 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.
@@ -1126,7 +1124,7 @@ pub struct NodesMatchingSuffix<'a, 'hir:'a> {
 }
 
 impl<'a, 'hir> NodesMatchingSuffix<'a, 'hir> {
-    /// Returns true only if some suffix of the module path for parent
+    /// Returns `true` only if some suffix of the module path for parent
     /// matches `self.in_which`.
     ///
     /// In other words: let `[x_0,x_1,...,x_k]` be `self.in_which`;

src/librustc/hir/mod.rs

@@ -62,14 +62,14 @@ pub mod map;
 pub mod pat_util;
 pub mod print;
 
-/// A HirId uniquely identifies a node in the HIR of the current crate. It is
+/// 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
+/// 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
 /// around within the source code, or add or remove stuff before it, without
-/// the local_id part of the HirId changing, which is a very useful property in
+/// the `local_id` part of the `HirId` changing, which is a very useful property in
 /// incremental compilation where we have to persist things through changes to
 /// the code base.
 #[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
@@ -130,7 +130,7 @@ mod item_local_id_inner {
 
 pub use self::item_local_id_inner::ItemLocalId;
 
-/// The `HirId` corresponding to CRATE_NODE_ID and CRATE_DEF_INDEX
+/// The `HirId` corresponding to `CRATE_NODE_ID` and `CRATE_DEF_INDEX`.
 pub const CRATE_HIR_ID: HirId = HirId {
     owner: CRATE_DEF_INDEX,
     local_id: ItemLocalId::from_u32_const(0)
@@ -149,8 +149,8 @@ pub struct Lifetime {
     pub hir_id: HirId,
     pub span: Span,
 
-    /// Either "'a", referring to a named lifetime definition,
+    /// Either "`'a`", referring to a named lifetime definition,
-    /// or "" (aka keywords::Invalid), for elision placeholders.
+    /// or "``" (i.e., `keywords::Invalid`), for elision placeholders.
     ///
     /// HIR lowering inserts these placeholders in type paths that
     /// refer to type definitions needing lifetime parameters,
@@ -163,8 +163,9 @@ pub enum ParamName {
     /// Some user-given name like `T` or `'x`.
     Plain(Ident),
 
-    /// Synthetic name generated when user elided a lifetime in an impl header,
+    /// 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
@@ -180,7 +181,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,
 }
 
@@ -205,17 +206,17 @@ pub enum LifetimeName {
     /// User-given names or fresh (synthetic) names.
     Param(ParamName),
 
-    /// User typed nothing. e.g., the lifetime in `&u32`.
+    /// User wrote nothing (e.g., the lifetime in `&u32`).
     Implicit,
 
     /// Indicates an error during lowering (usually `'_` in wrong place)
     /// that was already reported.
     Error,
 
-    /// User typed `'_`.
+    /// User wrote specifies `'_`.
     Underscore,
 
-    /// User wrote `'static`
+    /// User wrote `'static`.
     Static,
 }
 
@@ -280,7 +281,7 @@ impl Lifetime {
     }
 }
 
-/// A "Path" is essentially Rust's notion of a name; for instance:
+/// A `Path` is essentially Rust's notion of a name; for instance,
 /// `std::cmp::PartialEq`. It's represented as a sequence of identifiers,
 /// along with a bunch of supporting information.
 #[derive(Clone, RustcEncodable, RustcDecodable)]
@@ -340,7 +341,7 @@ pub struct PathSegment {
 }
 
 impl PathSegment {
-    /// Convert an identifier to the corresponding segment.
+    /// Converts an identifier to the corresponding segment.
     pub fn from_ident(ident: Ident) -> PathSegment {
         PathSegment {
             ident,
@@ -597,14 +598,14 @@ impl Generics {
     }
 }
 
-/// Synthetic Type Parameters are converted to an other form during lowering, this allows
+/// Synthetic type parameters are converted to another form during lowering; this allows
-/// to track the original form they had. Useful for error messages.
+/// us to track the original form they had, and is useful for error messages.
 #[derive(Copy, Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
 pub enum SyntheticTyParamKind {
     ImplTrait
 }
 
-/// A `where` clause in a definition
+/// A where-clause in a definition.
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct WhereClause {
     pub id: NodeId,
@@ -624,7 +625,7 @@ impl WhereClause {
     }
 }
 
-/// A single predicate in a `where` clause
+/// A single predicate in a where-clause.
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub enum WherePredicate {
     /// A type binding (e.g., `for<'c> Foo: Send + Clone + 'c`).
@@ -645,19 +646,19 @@ impl WherePredicate {
     }
 }
 
-/// A type bound, eg `for<'c> Foo: Send+Clone+'c`
+/// A type bound (e.g., `for<'c> Foo: Send + Clone + 'c`).
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct WhereBoundPredicate {
     pub span: Span,
-    /// Any generics from a `for` binding
+    /// Any generics from a `for` binding.
     pub bound_generic_params: HirVec<GenericParam>,
-    /// The type being bounded
+    /// The type being bounded.
     pub bounded_ty: P<Ty>,
-    /// Trait and lifetime bounds (`Clone+Send+'static`)
+    /// Trait and lifetime bounds (e.g., `Clone + Send + 'static`).
     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,
@@ -665,7 +666,7 @@ pub struct WhereRegionPredicate {
     pub bounds: GenericBounds,
 }
 
-/// An equality predicate (unsupported), e.g., `T=int`
+/// An equality predicate (e.g., `T = int`); currently unsupported.
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct WhereEqPredicate {
     pub id: NodeId,
@@ -759,7 +760,7 @@ impl Crate {
         }
     }
 
-    /// A parallel version of visit_all_item_likes
+    /// A parallel version of `visit_all_item_likes`.
     pub fn par_visit_all_item_likes<'hir, V>(&'hir self, visitor: &V)
         where V: itemlikevisit::ParItemLikeVisitor<'hir> + Sync + Send
     {
@@ -800,14 +801,14 @@ pub struct MacroDef {
 
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct Block {
-    /// Statements in a block
+    /// Statements in a block.
     pub stmts: HirVec<Stmt>,
     /// An expression at the end of the block
-    /// without a semicolon, if any
+    /// without a semicolon, if any.
     pub expr: Option<P<Expr>>,
     pub id: NodeId,
     pub hir_id: HirId,
-    /// Distinguishes between `unsafe { ... }` and `{ ... }`
+    /// Distinguishes between `unsafe { ... }` and `{ ... }`.
     pub rules: BlockCheckMode,
     pub span: Span,
     /// If true, then there may exist `break 'a` values that aim to
@@ -874,18 +875,18 @@ impl Pat {
     }
 }
 
-/// A single field in a struct pattern
+/// A single field in a struct pattern.
 ///
 /// Patterns like the fields of Foo `{ x, ref y, ref mut z }`
 /// are treated the same as` x: x, y: ref y, z: ref mut z`,
-/// except is_shorthand is true
+/// except `is_shorthand` is true.
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct FieldPat {
     pub id: NodeId,
     pub hir_id: HirId,
-    /// The identifier for the field
+    /// The identifier for the field.
     pub ident: Ident,
-    /// The pattern the field is destructured to
+    /// The pattern the field is destructured to.
     pub pat: P<Pat>,
     pub is_shorthand: bool,
 }
@@ -922,41 +923,41 @@ pub enum RangeEnd {
 
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub enum PatKind {
-    /// Represents a wildcard pattern (`_`)
+    /// Represents a wildcard pattern (i.e., `_`).
     Wild,
 
     /// 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, HirId, 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),
 
     /// A tuple struct/variant pattern `Variant(x, y, .., z)`.
     /// If the `..` pattern fragment is present, then `Option<usize>` denotes its position.
-    /// 0 <= position <= subpats.len()
+    /// `0 <= position <= subpats.len()`
     TupleStruct(QPath, HirVec<P<Pat>>, Option<usize>),
 
     /// A path pattern for an unit struct/variant or a (maybe-associated) constant.
     Path(QPath),
 
-    /// A tuple pattern `(a, b)`.
+    /// A tuple pattern (e.g., `(a, b)`).
     /// If the `..` pattern fragment is present, then `Option<usize>` denotes its position.
-    /// 0 <= position <= subpats.len()
+    /// `0 <= position <= subpats.len()`
     Tuple(HirVec<P<Pat>>, Option<usize>),
-    /// A `box` pattern
+    /// 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
+    /// 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])`
+    ///     `PatKind::Slice(box [a, b], Some(i), box [y, z])`.
     Slice(HirVec<P<Pat>>, Option<P<Pat>>, HirVec<P<Pat>>),
 }
 
@@ -967,7 +968,7 @@ pub enum Mutability {
 }
 
 impl Mutability {
-    /// Return MutMutable only if both arguments are mutable.
+    /// Returns `MutMutable` only if both arguments are mutable.
     pub fn and(self, other: Self) -> Self {
         match self {
             MutMutable => other,
@@ -978,41 +979,41 @@ impl Mutability {
 
 #[derive(Clone, PartialEq, RustcEncodable, RustcDecodable, Debug, Copy, Hash)]
 pub enum BinOpKind {
-    /// The `+` operator (addition)
+    /// The `+` operator (addition).
     Add,
-    /// The `-` operator (subtraction)
+    /// The `-` operator (subtraction).
     Sub,
-    /// The `*` operator (multiplication)
+    /// The `*` operator (multiplication).
     Mul,
-    /// The `/` operator (division)
+    /// The `/` operator (division).
     Div,
-    /// The `%` operator (modulus)
+    /// The `%` operator (modulus).
     Rem,
-    /// The `&&` operator (logical and)
+    /// The `&&` operator (logical and).
     And,
-    /// The `||` operator (logical or)
+    /// The `||` operator (logical or).
     Or,
-    /// The `^` operator (bitwise xor)
+    /// The `^` operator (bitwise xor).
     BitXor,
-    /// The `&` operator (bitwise and)
+    /// The `&` operator (bitwise and).
     BitAnd,
-    /// The `|` operator (bitwise or)
+    /// The `|` operator (bitwise or).
     BitOr,
-    /// The `<<` operator (shift left)
+    /// The `<<` operator (shift left).
     Shl,
-    /// The `>>` operator (shift right)
+    /// The `>>` operator (shift right).
     Shr,
-    /// The `==` operator (equality)
+    /// The `==` operator (equality).
     Eq,
-    /// The `<` operator (less than)
+    /// The `<` operator (less than).
     Lt,
-    /// The `<=` operator (less than or equal to)
+    /// The `<=` operator (less than or equal to).
     Le,
-    /// The `!=` operator (not equal to)
+    /// The `!=` operator (not equal to).
     Ne,
-    /// The `>=` operator (greater than or equal to)
+    /// The `>=` operator (greater than or equal to).
     Ge,
-    /// The `>` operator (greater than)
+    /// The `>` operator (greater than).
     Gt,
 }
 
@@ -1077,7 +1078,7 @@ impl BinOpKind {
         }
     }
 
-    /// Returns `true` if the binary operator takes its arguments by value
+    /// Returns `true` if the binary operator takes its arguments by value.
     pub fn is_by_value(self) -> bool {
         !self.is_comparison()
     }
@@ -1112,11 +1113,11 @@ pub type BinOp = Spanned<BinOpKind>;
 
 #[derive(Clone, PartialEq, RustcEncodable, RustcDecodable, Debug, Copy, Hash)]
 pub enum UnOp {
-    /// The `*` operator for dereferencing
+    /// The `*` operator (deferencing).
     UnDeref,
-    /// The `!` operator for logical inversion
+    /// The `!` operator (logical negation).
     UnNot,
-    /// The `-` operator for negation
+    /// The `-` operator (negation).
     UnNeg,
 }
 
@@ -1129,7 +1130,7 @@ impl UnOp {
         }
     }
 
-    /// Returns `true` if the unary operator takes its argument by value
+    /// Returns `true` if the unary operator takes its argument by value.
     pub fn is_by_value(self) -> bool {
         match self {
             UnNeg | UnNot => true,
@@ -1138,7 +1139,7 @@ impl UnOp {
     }
 }
 
-/// A statement
+/// A statement.
 #[derive(Clone, RustcEncodable, RustcDecodable)]
 pub struct Stmt {
     pub id: NodeId,
@@ -1156,15 +1157,15 @@ impl fmt::Debug for Stmt {
 
 #[derive(Clone, RustcEncodable, RustcDecodable)]
 pub enum StmtKind {
-    /// A local (let) binding:
+    /// A local (`let`) binding.
     Local(P<Local>),
-    /// An item binding:
+    /// An item binding.
     Item(P<ItemId>),
 
-    /// Expr without trailing semi-colon (must have unit type):
+    /// An expression without a trailing semi-colon (must have unit type).
     Expr(P<Expr>),
 
-    /// Expr with trailing semi-colon (may have any type):
+    /// An expression with a trailing semi-colon (may have any type).
     Semi(P<Expr>),
 }
 
@@ -1179,12 +1180,12 @@ impl StmtKind {
     }
 }
 
-/// Local represents a `let` statement, e.g., `let <pat>:<ty> = <expr>;`
+/// Represents a `let` statement (i.e., `let <pat>:<ty> = <expr>;`).
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct Local {
     pub pat: P<Pat>,
     pub ty: Option<P<Ty>>,
-    /// Initializer expression to set the value, if any
+    /// Initializer expression to set the value, if any.
     pub init: Option<P<Expr>>,
     pub id: NodeId,
     pub hir_id: HirId,
@@ -1193,7 +1194,7 @@ pub struct Local {
     pub source: LocalSource,
 }
 
-/// represents one arm of a 'match'
+/// Represents a single arm of a `match` expression.
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct Arm {
     pub attrs: HirVec<Attribute>,
@@ -1419,16 +1420,16 @@ impl fmt::Debug for Expr {
 pub enum ExprKind {
     /// A `box x` expression.
     Box(P<Expr>),
-    /// An array (`[a, b, c, d]`)
+    /// An array (e.g., `[a, b, c, d]`).
     Array(HirVec<Expr>),
-    /// A function call
+    /// A function call.
     ///
     /// The first field resolves to the function itself (usually an `ExprKind::Path`),
     /// and the second field is the list of arguments.
     /// This also represents calling the constructor of
     /// tuple-like ADTs such as tuple structs and enum variants.
     Call(P<Expr>, HirVec<Expr>),
-    /// A method call (`x.foo::<'static, Bar, Baz>(a, b, c, d)`)
+    /// A method call (e.g., `x.foo::<'static, Bar, Baz>(a, b, c, d)`).
     ///
     /// The `PathSegment`/`Span` represent the method name and its generic arguments
     /// (within the angle brackets).
@@ -1438,63 +1439,64 @@ pub enum ExprKind {
     /// Thus, `x.foo::<Bar, Baz>(a, b, c, d)` is represented as
     /// `ExprKind::MethodCall(PathSegment { foo, [Bar, Baz] }, [x, a, b, c, d])`.
     MethodCall(PathSegment, Span, HirVec<Expr>),
-    /// A tuple (`(a, b, c ,d)`)
+    /// A tuple (e.g., `(a, b, c ,d)`).
     Tup(HirVec<Expr>),
-    /// A binary operation (For example: `a + b`, `a * b`)
+    /// A binary operation (e.g., `a + b`, `a * b`).
     Binary(BinOp, P<Expr>, P<Expr>),
-    /// A unary operation (For example: `!x`, `*x`)
+    /// A unary operation (e.g., `!x`, `*x`).
     Unary(UnOp, P<Expr>),
-    /// A literal (For example: `1`, `"foo"`)
+    /// A literal (e.g., `1`, `"foo"`).
     Lit(Lit),
-    /// A cast (`foo as f64`)
+    /// A cast (e.g., `foo as f64`).
     Cast(P<Expr>, P<Ty>),
+    /// A type reference (e.g., `Foo`).
     Type(P<Expr>, P<Ty>),
-    /// An `if` block, with an optional else block
+    /// An `if` block, with an optional else block.
     ///
-    /// `if expr { expr } else { expr }`
+    /// I.e., `if <expr> { <expr> } else { <expr> }`.
     If(P<Expr>, P<Expr>, Option<P<Expr>>),
     /// A while loop, with an optional label
     ///
-    /// `'label: while expr { block }`
+    /// I.e., `'label: while expr { <block> }`.
     While(P<Expr>, P<Block>, Option<Label>),
-    /// Conditionless loop (can be exited with break, continue, or return)
+    /// A conditionless loop (can be exited with `break`, `continue`, or `return`).
     ///
-    /// `'label: loop { block }`
+    /// I.e., `'label: loop { <block> }`.
     Loop(P<Block>, Option<Label>, LoopSource),
     /// A `match` block, with a source that indicates whether or not it is
     /// the result of a desugaring, and if so, which kind.
     Match(P<Expr>, HirVec<Arm>, MatchSource),
-    /// A closure (for example, `move |a, b, c| {a + b + c}`).
+    /// A closure (e.g., `move |a, b, c| {a + b + c}`).
     ///
-    /// The final span is the span of the argument block `|...|`
+    /// The final span is the span of the argument block `|...|`.
     ///
     /// This may also be a generator literal, indicated by the final boolean,
-    /// in that case there is an GeneratorClause.
+    /// in that case there is an `GeneratorClause`.
     Closure(CaptureClause, P<FnDecl>, BodyId, Span, Option<GeneratorMovability>),
-    /// A block (`'label: { ... }`)
+    /// A block (e.g., `'label: { ... }`).
     Block(P<Block>, Option<Label>),
 
-    /// An assignment (`a = foo()`)
+    /// An assignment (e.g., `a = foo()`).
     Assign(P<Expr>, P<Expr>),
-    /// An assignment with an operator
+    /// An assignment with an operator.
     ///
-    /// For example, `a += 1`.
+    /// E.g., `a += 1`.
     AssignOp(BinOp, P<Expr>, P<Expr>),
-    /// Access of a named (`obj.foo`) or unnamed (`obj.0`) struct or tuple field
+    /// Access of a named (e.g., `obj.foo`) or unnamed (e.g., `obj.0`) struct or tuple field.
     Field(P<Expr>, Ident),
-    /// An indexing operation (`foo[2]`)
+    /// An indexing operation (`foo[2]`).
     Index(P<Expr>, P<Expr>),
 
     /// Path to a definition, possibly containing lifetime or type parameters.
     Path(QPath),
 
-    /// A referencing operation (`&a` or `&mut a`)
+    /// A referencing operation (i.e., `&a` or `&mut a`).
     AddrOf(Mutability, P<Expr>),
-    /// A `break`, with an optional label to break
+    /// A `break`, with an optional label to break.
     Break(Destination, Option<P<Expr>>),
-    /// A `continue`, with an optional label
+    /// A `continue`, with an optional label.
     Continue(Destination),
-    /// A `return`, with an optional value to be returned
+    /// A `return`, with an optional value to be returned.
     Ret(Option<P<Expr>>),
 
     /// Inline assembly (from `asm!`), with its outputs and inputs.
@@ -1512,10 +1514,10 @@ pub enum ExprKind {
     /// to be repeated; the second is the number of times to repeat it.
     Repeat(P<Expr>, AnonConst),
 
-    /// A suspension point for generators. This is `yield <expr>` in Rust.
+    /// A suspension point for generators (i.e., `yield <expr>`).
     Yield(P<Expr>),
 
-    /// Placeholder for an expression that wasn't syntactically well formed in some way.
+    /// A placeholder for an expression that wasn't syntactically well formed in some way.
     Err,
 }
 
@@ -1525,12 +1527,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
@@ -1539,41 +1541,41 @@ pub enum QPath {
     TypeRelative(P<Ty>, P<PathSegment>)
 }
 
-/// Hints at the original code for a let statement
+/// Hints at the original code for a let statement.
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug, Copy)]
 pub enum LocalSource {
-    /// A `match _ { .. }`
+    /// A `match _ { .. }`.
     Normal,
-    /// A desugared `for _ in _ { .. }` loop
+    /// A desugared `for _ in _ { .. }` loop.
     ForLoopDesugar,
 }
 
-/// Hints at the original code for a `match _ { .. }`
+/// Hints at the original code for a `match _ { .. }`.
 #[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug, Copy)]
 pub enum MatchSource {
-    /// A `match _ { .. }`
+    /// A `match _ { .. }`.
     Normal,
-    /// An `if let _ = _ { .. }` (optionally with `else { .. }`)
+    /// An `if let _ = _ { .. }` (optionally with `else { .. }`).
     IfLetDesugar {
         contains_else_clause: bool,
     },
     /// A `while let _ = _ { .. }` (which was desugared to a
-    /// `loop { match _ { .. } }`)
+    /// `loop { match _ { .. } }`).
     WhileLetDesugar,
-    /// A desugared `for _ in _ { .. }` loop
+    /// A desugared `for _ in _ { .. }` loop.
     ForLoopDesugar,
-    /// A desugared `?` operator
+    /// A desugared `?` operator.
     TryDesugar,
 }
 
-/// The loop type that yielded an ExprKind::Loop
+/// The loop type that yielded an `ExprKind::Loop`.
 #[derive(Clone, PartialEq, RustcEncodable, RustcDecodable, Debug, Copy)]
 pub enum LoopSource {
-    /// A `loop { .. }` loop
+    /// A `loop { .. }` loop.
     Loop,
-    /// A `while let _ = _ { .. }` loop
+    /// A `while let _ = _ { .. }` loop.
     WhileLet,
-    /// A `for _ in _ { .. }` loop
+    /// A `for _ in _ { .. }` loop.
     ForLoop,
 }
 
@@ -1739,7 +1741,7 @@ impl fmt::Debug for Ty {
     }
 }
 
-/// Not represented directly in the AST, referred to by name through a ty_path.
+/// Not represented directly in the AST; referred to by name through a `ty_path`.
 #[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug, Copy)]
 pub enum PrimTy {
     Int(IntTy),
@@ -1766,38 +1768,38 @@ pub struct ExistTy {
     pub impl_trait_fn: Option<DefId>,
 }
 
+/// The various kinds of types recognized by the compiler.
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
-/// The different kinds of types recognized by the compiler
 pub enum TyKind {
-    /// A variable length slice (`[T]`)
+    /// A variable length slice (i.e., `[T]`).
     Slice(P<Ty>),
-    /// A fixed length array (`[T; n]`)
+    /// A fixed length array (i.e., `[T; n]`).
     Array(P<Ty>, AnonConst),
-    /// A raw pointer (`*const T` or `*mut T`)
+    /// A raw pointer (i.e., `*const T` or `*mut T`).
     Ptr(MutTy),
-    /// A reference (`&'a T` or `&'a mut T`)
+    /// A reference (i.e., `&'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 (`!`)
+    /// The never type (`!`).
     Never,
-    /// A tuple (`(A, B, C, D,...)`)
+    /// 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),
     /// A type definition itself. This is currently only used for the `existential type`
     /// item that `impl Trait` in return position desugars to.
     ///
-    /// The generic arg list are the lifetimes (and in the future possibly parameters) that are
+    /// The generic argument list contains the lifetimes (and in the future possibly parameters)
-    /// actually bound on the `impl Trait`.
+    /// that are actually bound on the `impl Trait`.
     Def(ItemId, HirVec<GenericArg>),
     /// A trait object type `Bound1 + Bound2 + Bound3`
     /// where `Bound` is a trait or a lifetime.
     TraitObject(HirVec<PolyTraitRef>, Lifetime),
-    /// Unused for now
+    /// Unused for now.
     Typeof(AnonConst),
     /// `TyKind::Infer` means the type should be inferred instead of it having been
     /// specified. This can appear anywhere in a type.
@@ -1827,7 +1829,7 @@ pub struct InlineAsm {
     pub ctxt: SyntaxContext,
 }
 
-/// represents an argument in a function header
+/// Represents an argument in a function header.
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct Arg {
     pub pat: P<Pat>,
@@ -1835,7 +1837,7 @@ pub struct Arg {
     pub hir_id: HirId,
 }
 
-/// Represents the header (not the body) of a function declaration
+/// Represents the header (not the body) of a function declaration.
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct FnDecl {
     pub inputs: HirVec<Ty>,
@@ -1958,7 +1960,7 @@ pub enum FunctionRetTy {
     /// closures default to inference. Span points to where return
     /// type would be inserted.
     DefaultReturn(Span),
-    /// Everything else
+    /// Everything else.
     Return(P<Ty>),
 }
 
@@ -2011,7 +2013,7 @@ pub struct VariantKind {
     pub ident: Ident,
     pub attrs: HirVec<Attribute>,
     pub data: VariantData,
-    /// Explicit discriminant, e.g., `Foo = 1`
+    /// Explicit discriminant (e.g., `Foo = 1`).
     pub disr_expr: Option<AnonConst>,
 }
 
@@ -2047,7 +2049,7 @@ pub struct TraitRef {
 }
 
 impl TraitRef {
-    /// Get the `DefId` of the referenced trait. It _must_ actually be a trait or trait alias.
+    /// Gets the `DefId` of the referenced trait. It _must_ actually be a trait or trait alias.
     pub fn trait_def_id(&self) -> DefId {
         match self.path.def {
             Def::Trait(did) => did,
@@ -2062,10 +2064,10 @@ impl TraitRef {
 
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct PolyTraitRef {
-    /// The `'a` in `<'a> Foo<&'a T>`
+    /// The `'a` in `<'a> Foo<&'a T>`.
     pub bound_generic_params: HirVec<GenericParam>,
 
-    /// The `Foo<&'a T>` in `<'a> Foo<&'a T>`
+    /// The `Foo<&'a T>` in `<'a> Foo<&'a T>`.
     pub trait_ref: TraitRef,
 
     pub span: Span,
@@ -2223,7 +2225,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;`
@@ -2320,7 +2322,7 @@ impl ItemKind {
 /// contains the item's id, naturally, but also the item's name and
 /// some other high-level details (like whether it is an associated
 /// type or method, and whether it is public). This allows other
-/// passes to find the impl they want without loading the id (which
+/// passes to find the impl they want without loading the ID (which
 /// means fewer edges in the incremental compilation graph).
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct TraitItemRef {
@@ -2332,10 +2334,10 @@ pub struct TraitItemRef {
 }
 
 /// A reference from an impl to one of its associated items. This
-/// contains the item's id, naturally, but also the item's name and
+/// contains the item's ID, naturally, but also the item's name and
 /// some other high-level details (like whether it is an associated
 /// type or method, and whether it is public). This allows other
-/// passes to find the impl they want without loading the id (which
+/// passes to find the impl they want without loading the ID (which
 /// means fewer edges in the incremental compilation graph).
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub struct ImplItemRef {
@@ -2366,15 +2368,15 @@ pub struct ForeignItem {
     pub vis: Visibility,
 }
 
-/// An item within an `extern` block
+/// An item within an `extern` block.
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug)]
 pub enum ForeignItemKind {
-    /// A foreign function
+    /// A foreign function.
     Fn(P<FnDecl>, HirVec<Ident>, Generics),
     /// A foreign static item (`static ext: u8`), with optional mutability
-    /// (the boolean is true when mutable)
+    /// (the boolean is true when mutable).
     Static(P<Ty>, bool),
-    /// A foreign type
+    /// A foreign type.
     Type,
 }
 
@@ -2458,36 +2460,37 @@ pub struct CodegenFnAttrs {
 bitflags! {
     #[derive(RustcEncodable, RustcDecodable)]
     pub struct CodegenFnAttrFlags: u32 {
-        /// #[cold], a hint to LLVM that this function, when called, is never on
+        /// `#[cold]`: a hint to LLVM that this function, when called, is never on
-        /// the hot path
+        /// the hot path.
         const COLD                      = 1 << 0;
-        /// #[allocator], a hint to LLVM that the pointer returned from this
+        /// `#[allocator]`: a hint to LLVM that the pointer returned from this
-        /// function is never null
+        /// function is never null.
         const ALLOCATOR                 = 1 << 1;
-        /// #[unwind], an indicator that this function may unwind despite what
+        /// `#[unwind]`: an indicator that this function may unwind despite what
-        /// its ABI signature may otherwise imply
+        /// its ABI signature may otherwise imply.
         const UNWIND                    = 1 << 2;
-        /// #[rust_allocator_nounwind], an indicator that an imported FFI
+        /// `#[rust_allocator_nounwind]`, an indicator that an imported FFI
         /// function will never unwind. Probably obsolete by recent changes with
         /// #[unwind], but hasn't been removed/migrated yet
         const RUSTC_ALLOCATOR_NOUNWIND  = 1 << 3;
-        /// #[naked], indicates to LLVM that no function prologue/epilogue
+        /// `#[naked]`: an indicator to LLVM that no function prologue/epilogue
-        /// should be generated
+        /// should be generated.
         const NAKED                     = 1 << 4;
-        /// #[no_mangle], the function's name should be the same as its symbol
+        /// `#[no_mangle]`: an indicator that the function's name should be the same
+        /// as its symbol.
         const NO_MANGLE                 = 1 << 5;
-        /// #[rustc_std_internal_symbol], and indicator that this symbol is a
+        /// `#[rustc_std_internal_symbol]`: an indicator that this symbol is a
         /// "weird symbol" for the standard library in that it has slightly
         /// different linkage, visibility, and reachability rules.
         const RUSTC_STD_INTERNAL_SYMBOL = 1 << 6;
-        /// #[no_debug], indicates that no debugging information should be
+        /// `#[no_debug]`: an indicator that no debugging information should be
-        /// generated for this function by LLVM
+        /// generated for this function by LLVM.
         const NO_DEBUG                  = 1 << 7;
-        /// #[thread_local], indicates a static is actually a thread local
+        /// `#[thread_local]`: indicates a static is actually a thread local
         /// piece of memory
         const THREAD_LOCAL              = 1 << 8;
-        /// #[used], indicates that LLVM can't eliminate this function (but the
+        /// `#[used]`: indicates that LLVM can't eliminate this function (but the
-        /// linker can!)
+        /// linker can!).
         const USED                      = 1 << 9;
     }
 }
@@ -2506,7 +2509,7 @@ impl CodegenFnAttrs {
         }
     }
 
-    /// True if `#[inline]` or `#[inline(always)]` is present.
+    /// Returns `true` if `#[inline]` or `#[inline(always)]` is present.
     pub fn requests_inline(&self) -> bool {
         match self.inline {
             InlineAttr::Hint | InlineAttr::Always => true,

src/librustc/hir/pat_util.rs

@@ -129,7 +129,7 @@ impl hir::Pat {
         }
     }
 
-    /// Return variants that are necessary to exist for the pattern to match.
+    /// Returns variants that are necessary to exist for the pattern to match.
     pub fn necessary_variants(&self) -> Vec<DefId> {
         let mut variants = vec![];
         self.walk(|p| {
@@ -154,11 +154,9 @@ impl hir::Pat {
 
     /// Checks if the pattern contains any `ref` or `ref mut` bindings, and if
     /// yes whether it contains mutable or just immutables ones.
-    ///
+    //
-    /// FIXME(tschottdorf): this is problematic as the HIR is being scraped, but
+    // FIXME(tschottdorf): this is problematic as the HIR is being scraped, but
-    /// ref bindings are be implicit after #42640 (default match binding modes).
+    // ref bindings are be implicit after #42640 (default match binding modes). See issue #44848.
-    ///
-    /// See #44848.
     pub fn contains_explicit_ref_binding(&self) -> Option<hir::Mutability> {
         let mut result = None;
         self.each_binding(|annotation, _, _, _| {

src/librustc/infer/at.rs

@@ -78,7 +78,7 @@ impl<'a, 'gcx, 'tcx> At<'a, 'gcx, 'tcx> {
         }
     }
 
-    /// Make `a <: b` where `a` may or may not be expected
+    /// Makes `a <: b`, where `a` may or may not be expected.
     pub fn sub_exp<T>(self,
                       a_is_expected: bool,
                       a: T,
@@ -89,7 +89,7 @@ impl<'a, 'gcx, 'tcx> At<'a, 'gcx, 'tcx> {
         self.trace_exp(a_is_expected, a, b).sub(&a, &b)
     }
 
-    /// Make `actual <: expected`. For example, if type-checking a
+    /// Makes `actual <: expected`. For example, if type-checking a
     /// call like `foo(x)`, where `foo: fn(i32)`, you might have
     /// `sup(i32, x)`, since the "expected" type is the type that
     /// appears in the signature.
@@ -102,7 +102,7 @@ impl<'a, 'gcx, 'tcx> At<'a, 'gcx, 'tcx> {
         self.sub_exp(false, actual, expected)
     }
 
-    /// Make `expected <: actual`
+    /// Makes `expected <: actual`.
     pub fn sub<T>(self,
                   expected: T,
                   actual: T)
@@ -112,7 +112,7 @@ impl<'a, 'gcx, 'tcx> At<'a, 'gcx, 'tcx> {
         self.sub_exp(true, expected, actual)
     }
 
-    /// Make `expected <: actual`
+    /// Makes `expected <: actual`.
     pub fn eq_exp<T>(self,
                      a_is_expected: bool,
                      a: T,
@@ -123,7 +123,7 @@ impl<'a, 'gcx, 'tcx> At<'a, 'gcx, 'tcx> {
         self.trace_exp(a_is_expected, a, b).eq(&a, &b)
     }
 
-    /// Make `expected <: actual`
+    /// Makes `expected <: actual`.
     pub fn eq<T>(self,
                  expected: T,
                  actual: T)
@@ -155,7 +155,7 @@ impl<'a, 'gcx, 'tcx> At<'a, 'gcx, 'tcx> {
         }
     }
 
-    /// Compute the least-upper-bound, or mutual supertype, of two
+    /// Computes the least-upper-bound, or mutual supertype, of two
     /// values. The order of the arguments doesn't matter, but since
     /// this can result in an error (e.g., if asked to compute LUB of
     /// u32 and i32), it is meaningful to call one of them the
@@ -169,7 +169,7 @@ impl<'a, 'gcx, 'tcx> At<'a, 'gcx, 'tcx> {
         self.trace(expected, actual).lub(&expected, &actual)
     }
 
-    /// Compute the greatest-lower-bound, or mutual subtype, of two
+    /// Computes the greatest-lower-bound, or mutual subtype, of two
     /// values. As with `lub` order doesn't matter, except for error
     /// cases.
     pub fn glb<T>(self,
@@ -210,9 +210,9 @@ impl<'a, 'gcx, 'tcx> At<'a, 'gcx, 'tcx> {
 }
 
 impl<'a, 'gcx, 'tcx> Trace<'a, 'gcx, 'tcx> {
-    /// Make `a <: b` where `a` may or may not be expected (if
+    /// Makes `a <: b` where `a` may or may not be expected (if
     /// `a_is_expected` is true, then `a` is expected).
-    /// Make `expected <: actual`
+    /// Makes `expected <: actual`.
     pub fn sub<T>(self,
                   a: &T,
                   b: &T)
@@ -229,7 +229,7 @@ impl<'a, 'gcx, 'tcx> Trace<'a, 'gcx, 'tcx> {
         })
     }
 
-    /// Make `a == b`; the expectation is set by the call to
+    /// Makes `a == b`; the expectation is set by the call to
     /// `trace()`.
     pub fn eq<T>(self,
                  a: &T,

src/librustc/infer/canonical/canonicalizer.rs

@@ -117,9 +117,9 @@ impl<'cx, 'gcx, 'tcx> InferCtxt<'cx, 'gcx, 'tcx> {
     /// #33684), so if we are performing an operation that may need to
     /// prove "leak-check" related things, we leave `'static`
     /// alone.
-    ///
+    //
-    /// FIXME(#48536) -- once we have universes, we can remove this and just use
+    // FIXME(#48536): once we have universes, we can remove this and just use
-    /// `canonicalize_query`.
+    // `canonicalize_query`.
     pub fn canonicalize_hr_query_hack<V>(
         &self,
         value: &V,
@@ -595,7 +595,7 @@ impl<'cx, 'gcx, 'tcx> Canonicalizer<'cx, 'gcx, 'tcx> {
             .var_universe(vid)
     }
 
-    /// Create a canonical variable (with the given `info`)
+    /// Creates a canonical variable (with the given `info`)
     /// representing the region `r`; return a region referencing it.
     fn canonical_var_for_region(
         &mut self,

src/librustc/infer/canonical/mod.rs

@@ -424,7 +424,7 @@ impl<'tcx> CanonicalVarValues<'tcx> {
         self.var_values.len()
     }
 
-    /// Make an identity substitution from this one: each bound var
+    /// Makes an identity substitution from this one: each bound var
     /// is matched to the same bound var, preserving the original kinds.
     /// For example, if we have:
     /// `self.var_values == [Type(u32), Lifetime('a), Type(u64)]`

src/librustc/infer/canonical/query_response.rs

@@ -119,7 +119,7 @@ impl<'cx, 'gcx, 'tcx> InferCtxt<'cx, 'gcx, 'tcx> {
     /// If you DO want to keep track of pending obligations (which
     /// include all region obligations, so this includes all cases
     /// that care about regions) with this function, you have to
-    /// do it yourself, by e.g. having them be a part of the answer.
+    /// do it yourself, by e.g., having them be a part of the answer.
     pub fn make_query_response_ignoring_pending_obligations<T>(
         &self,
         inference_vars: CanonicalVarValues<'tcx>,

src/librustc/infer/combine.rs

@@ -165,8 +165,8 @@ impl<'infcx, 'gcx, 'tcx> CombineFields<'infcx, 'gcx, 'tcx> {
         Glb::new(self, a_is_expected)
     }
 
-    /// Here dir is either EqTo, SubtypeOf, or SupertypeOf. The
+    /// Here, `dir` is either `EqTo`, `SubtypeOf`, or `SupertypeOf`.
-    /// idea is that we should ensure that the type `a_ty` is equal
+    /// The idea is that we should ensure that the type `a_ty` is equal
     /// to, a subtype of, or a supertype of (respectively) the type
     /// to which `b_vid` is bound.
     ///
@@ -280,7 +280,7 @@ impl<'infcx, 'gcx, 'tcx> CombineFields<'infcx, 'gcx, 'tcx> {
 struct Generalizer<'cx, 'gcx: 'cx+'tcx, 'tcx: 'cx> {
     infcx: &'cx InferCtxt<'cx, 'gcx, 'tcx>,
 
-    /// Span, used when creating new type variables and things.
+    /// The span, used when creating new type variables and things.
     span: Span,
 
     /// The vid of the type variable that is in the process of being

src/librustc/infer/error_reporting/mod.rs

@@ -659,7 +659,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
         None
     }
 
-    /// Add a `,` to the type representation only if it is appropriate.
+    /// Adds a `,` to the type representation only if it is appropriate.
     fn push_comma(
         &self,
         value: &mut DiagnosticStyledString,
@@ -715,7 +715,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
         substs.truncate_to(self.tcx, &generics)
     }
 
-    /// Compare two given types, eliding parts that are the same between them and highlighting
+    /// Compares two given types, eliding parts that are the same between them and highlighting
     /// relevant differences, and return two representation of those types for highlighted printing.
     fn cmp(&self, t1: Ty<'tcx>, t2: Ty<'tcx>) -> (DiagnosticStyledString, DiagnosticStyledString) {
         fn equals<'tcx>(a: &Ty<'tcx>, b: &Ty<'tcx>) -> bool {

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

@@ -39,7 +39,7 @@ impl<'a, 'gcx, 'tcx> NiceRegionError<'a, 'gcx, 'tcx> {
     ///     x.push(y);
     ///     ^ ...but data from `y` flows into `x` here
     /// }
-    /// ````
+    /// ```
     ///
     /// It will later be extended to trait objects.
     pub(super) fn try_report_anon_anon_conflict(&self) -> Option<ErrorReported> {

src/librustc/infer/higher_ranked/mod.rs

@@ -54,7 +54,7 @@ impl<'a, 'gcx, 'tcx> CombineFields<'a, 'gcx, 'tcx> {
 }
 
 impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
-    /// Replace all regions (resp. types) bound by `binder` with placeholder
+    /// Replaces all regions (resp. types) bound by `binder` with placeholder
     /// regions (resp. types) and return a map indicating which bound-region
     /// placeholder region. This is the first step of checking subtyping
     /// when higher-ranked things are involved.

src/librustc/infer/lexical_region_resolve/mod.rs

@@ -1,4 +1,4 @@
-//! The code to do lexical region resolution.
+//! Lexical region resolution.
 
 use crate::infer::region_constraints::Constraint;
 use crate::infer::region_constraints::GenericKind;
@@ -492,11 +492,11 @@ impl<'cx, 'gcx, 'tcx> LexicalResolver<'cx, 'gcx, 'tcx> {
             match *value {
                 VarValue::Value(_) => { /* Inference successful */ }
                 VarValue::ErrorValue => {
-                    /* Inference impossible, this value contains
+                    /* Inference impossible: this value contains
                        inconsistent constraints.
 
                        I think that in this case we should report an
-                       error now---unlike the case above, we can't
+                       error now -- unlike the case above, we can't
                        wait to see whether the user needs the result
                        of this variable. The reason is that the mere
                        existence of this variable implies that the

src/librustc/infer/mod.rs

@@ -221,7 +221,7 @@ pub struct InferCtxt<'a, 'gcx: 'a + 'tcx, 'tcx: 'a> {
 /// replaced with.
 pub type PlaceholderMap<'tcx> = BTreeMap<ty::BoundRegion, ty::Region<'tcx>>;
 
-/// See `error_reporting` module for more details
+/// See the `error_reporting` module for more details.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum ValuePairs<'tcx> {
     Types(ExpectedFound<Ty<'tcx>>),
@@ -233,7 +233,7 @@ pub enum ValuePairs<'tcx> {
 /// The trace designates the path through inference that we took to
 /// encounter an error or subtyping constraint.
 ///
-/// See `error_reporting` module for more details.
+/// See the `error_reporting` module for more details.
 #[derive(Clone)]
 pub struct TypeTrace<'tcx> {
     cause: ObligationCause<'tcx>,
@@ -454,9 +454,9 @@ impl fmt::Display for FixupError {
     }
 }
 
-/// Helper type of a temporary returned by tcx.infer_ctxt().
+/// Helper type of a temporary returned by `tcx.infer_ctxt()`.
 /// Necessary because we can't write the following bound:
-/// F: for<'b, 'tcx> where 'gcx: 'tcx FnOnce(InferCtxt<'b, 'gcx, 'tcx>).
+/// `F: for<'b, 'tcx> where 'gcx: 'tcx FnOnce(InferCtxt<'b, 'gcx, 'tcx>)`.
 pub struct InferCtxtBuilder<'a, 'gcx: 'a + 'tcx, 'tcx: 'a> {
     global_tcx: TyCtxt<'a, 'gcx, 'gcx>,
     arena: SyncDroplessArena,
@@ -563,7 +563,7 @@ impl<'tcx, T> InferOk<'tcx, T> {
         }
     }
 
-    /// Extract `value`, registering any obligations into `fulfill_cx`
+    /// Extracts `value`, registering any obligations into `fulfill_cx`.
     pub fn into_value_registering_obligations(
         self,
         infcx: &InferCtxt<'_, '_, 'tcx>,
@@ -794,7 +794,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
             .commit(region_constraints_snapshot);
     }
 
-    /// Execute `f` and commit the bindings
+    /// Executes `f` and commit the bindings.
     pub fn commit_unconditionally<R, F>(&self, f: F) -> R
     where
         F: FnOnce() -> R,
@@ -806,7 +806,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
         r
     }
 
-    /// Execute `f` and commit the bindings if closure `f` returns `Ok(_)`
+    /// Executes `f` and commit the bindings if closure `f` returns `Ok(_)`.
     pub fn commit_if_ok<T, E, F>(&self, f: F) -> Result<T, E>
     where
         F: FnOnce(&CombinedSnapshot<'a, 'tcx>) -> Result<T, E>,
@@ -838,7 +838,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
         r
     }
 
-    /// Execute `f` then unroll any bindings it creates
+    /// Executes `f` then unroll any bindings it creates.
     pub fn probe<R, F>(&self, f: F) -> R
     where
         F: FnOnce(&CombinedSnapshot<'a, 'tcx>) -> R,
@@ -996,14 +996,14 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
         self.float_unification_table.borrow_mut().new_key(None)
     }
 
-    /// Create a fresh region variable with the next available index.
+    /// Creates a fresh region variable with the next available index.
     /// The variable will be created in the maximum universe created
     /// thus far, allowing it to name any region created thus far.
     pub fn next_region_var(&self, origin: RegionVariableOrigin) -> ty::Region<'tcx> {
         self.next_region_var_in_universe(origin, self.universe())
     }
 
-    /// Create a fresh region variable with the next available index
+    /// Creates a fresh region variable with the next available index
     /// in the given universe; typically, you can use
     /// `next_region_var` and just use the maximal universe.
     pub fn next_region_var_in_universe(
@@ -1069,7 +1069,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
         Substs::for_item(self.tcx, def_id, |param, _| self.var_for_def(span, param))
     }
 
-    /// True if errors have been reported since this infcx was
+    /// Returns `true` if errors have been reported since this infcx was
     /// created. This is sometimes used as a heuristic to skip
     /// reporting errors that often occur as a result of earlier
     /// errors, but where it's hard to be 100% sure (e.g., unresolved
@@ -1278,7 +1278,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
         value.fold_with(&mut r)
     }
 
-    /// Returns true if `T` contains unresolved type variables. In the
+    /// Returns `true` if `T` contains unresolved type variables. In the
     /// process of visiting `T`, this will resolve (where possible)
     /// type variables in `T`, but it never constructs the final,
     /// resolved type, so it's more efficient than
@@ -1361,7 +1361,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
         self.tcx.replace_bound_vars(value, fld_r, fld_t)
     }
 
-    /// See `verify_generic_bound` method in `region_constraints`
+    /// See the [`region_constraints::verify_generic_bound`] method.
     pub fn verify_generic_bound(
         &self,
         origin: SubregionOrigin<'tcx>,
@@ -1458,8 +1458,8 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
     }
 
     /// Clears the selection, evaluation, and projection caches. This is useful when
-    /// repeatedly attempting to select an Obligation while changing only
+    /// repeatedly attempting to select an `Obligation` while changing only
-    /// its ParamEnv, since FulfillmentContext doesn't use 'probe'
+    /// its `ParamEnv`, since `FulfillmentContext` doesn't use probing.
     pub fn clear_caches(&self) {
         self.selection_cache.clear();
         self.evaluation_cache.clear();
@@ -1470,7 +1470,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
         self.universe.get()
     }
 
-    /// Create and return a fresh universe that extends all previous
+    /// Creates and return a fresh universe that extends all previous
     /// universes. Updates `self.universe` to that new universe.
     pub fn create_next_universe(&self) -> ty::UniverseIndex {
         let u = self.universe.get().next_universe();

src/librustc/infer/nll_relate/mod.rs

@@ -47,17 +47,17 @@ where
 
     /// How are we relating `a` and `b`?
     ///
-    /// - covariant means `a <: b`
+    /// - Covariant means `a <: b`.
-    /// - contravariant means `b <: a`
+    /// - Contravariant means `b <: a`.
-    /// - invariant means `a == b
+    /// - Invariant means `a == b.
-    /// - bivariant means that it doesn't matter
+    /// - Bivariant means that it doesn't matter.
     ambient_variance: ty::Variance,
 
     /// When we pass through a set of binders (e.g., when looking into
     /// a `fn` type), we push a new bound region scope onto here. This
     /// will contain the instantiated region for each region in those
     /// binders. When we then encounter a `ReLateBound(d, br)`, we can
-    /// use the debruijn index `d` to find the right scope, and then
+    /// use the De Bruijn index `d` to find the right scope, and then
     /// bound region name `br` to find the specific instantiation from
     /// within that scope. See `replace_bound_region`.
     ///
@@ -114,7 +114,7 @@ pub trait TypeRelatingDelegate<'tcx> {
     /// Define the normalization strategy to use, eager or lazy.
     fn normalization() -> NormalizationStrategy;
 
-    /// Enable some optimizations if we do not expect inference variables
+    /// Enables some optimizations if we do not expect inference variables
     /// in the RHS of the relation.
     fn forbid_inference_vars() -> bool;
 }
@@ -208,7 +208,7 @@ where
     /// When we encounter binders during the type traversal, we record
     /// the value to substitute for each of the things contained in
     /// that binder. (This will be either a universal placeholder or
-    /// an existential inference variable.) Given the debruijn index
+    /// an existential inference variable.) Given the De Bruijn index
     /// `debruijn` (and name `br`) of some binder we have now
     /// encountered, this routine finds the value that we instantiated
     /// the region with; to do so, it indexes backwards into the list

src/librustc/infer/opaque_types/mod.rs

@@ -46,7 +46,7 @@ pub struct OpaqueTypeDecl<'tcx> {
     /// lifetime parameter on `foo`.)
     pub concrete_ty: Ty<'tcx>,
 
-    /// True if the `impl Trait` bounds include region bounds.
+    /// Returns `true` if the `impl Trait` bounds include region bounds.
     /// For example, this would be true for:
     ///
     ///     fn foo<'a, 'b, 'c>() -> impl Trait<'c> + 'a + 'b
@@ -71,7 +71,7 @@ pub struct OpaqueTypeDecl<'tcx> {
 }
 
 impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
-    /// Replace all opaque types in `value` with fresh inference variables
+    /// Replaces all opaque types in `value` with fresh inference variables
     /// and creates appropriate obligations. For example, given the input:
     ///
     ///     impl Iterator<Item = impl Debug>
@@ -88,7 +88,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
     ///
     /// # Parameters
     ///
-    /// - `parent_def_id` -- the def-id of the function in which the opaque type
+    /// - `parent_def_id` -- the `DefId` of the function in which the opaque type
     ///   is defined
     /// - `body_id` -- the body-id with which the resulting obligations should
     ///   be associated
@@ -813,7 +813,7 @@ impl<'a, 'gcx, 'tcx> Instantiator<'a, 'gcx, 'tcx> {
     }
 }
 
-/// Whether `opaque_node_id` is a sibling or a child of a sibling of `def_id`
+/// Returns `true` if `opaque_node_id` is a sibling or a child of a sibling of `def_id`.
 ///
 /// ```rust
 /// pub mod foo {
@@ -827,11 +827,10 @@ impl<'a, 'gcx, 'tcx> Instantiator<'a, 'gcx, 'tcx> {
 /// }
 /// ```
 ///
-/// Here, `def_id` will be the `DefId` of the existential type `Baz`.
+/// Here, `def_id` is the `DefId` of the existential type `Baz` and `opaque_node_id` is the
-/// `opaque_node_id` is the `NodeId` of the reference to Baz --
+/// `NodeId` of the reference to `Baz` (i.e., the return type of both `f1` and `f2`).
-///  so either the return type of f1 or f2.
+/// We return `true` if the reference is within the same module as the existential type
-/// We will return true if the reference is within the same module as the existential type
+/// (i.e., `true` for `f1`, `false` for `f2`).
-/// So true for f1, false for f2.
 pub fn may_define_existential_type(
     tcx: TyCtxt<'_, '_, '_>,
     def_id: DefId,

src/librustc/infer/outlives/env.rs

@@ -63,7 +63,7 @@ pub struct OutlivesEnvironment<'tcx> {
 }
 
 /// "Region-bound pairs" tracks outlives relations that are known to
-/// be true, either because of explicit where clauses like `T: 'a` or
+/// be true, either because of explicit where-clauses like `T: 'a` or
 /// because of implied bounds.
 pub type RegionBoundPairs<'tcx> = Vec<(ty::Region<'tcx>, GenericKind<'tcx>)>;
 

src/librustc/infer/outlives/free_region_map.rs

@@ -24,7 +24,7 @@ impl<'tcx> FreeRegionMap<'tcx> {
         }
     }
 
-    /// Compute the least-upper-bound of two free regions. In some
+    /// Computes the least-upper-bound of two free regions. In some
     /// cases, this is more conservative than necessary, in order to
     /// avoid making arbitrary choices. See
     /// `TransitiveRelation::postdom_upper_bound` for more details.

src/librustc/infer/outlives/verify.rs

@@ -96,7 +96,7 @@ impl<'cx, 'gcx, 'tcx> VerifyBoundCx<'cx, 'gcx, 'tcx> {
         })
     }
 
-    /// Searches the where clauses in scope for regions that
+    /// Searches the where-clauses in scope for regions that
     /// `projection_ty` is known to outlive. Currently requires an
     /// exact match.
     pub fn projection_declared_bounds_from_trait(
@@ -251,7 +251,7 @@ impl<'cx, 'gcx, 'tcx> VerifyBoundCx<'cx, 'gcx, 'tcx> {
             .map(move |r| r.subst(tcx, projection_ty.substs))
     }
 
-    /// Given the def-id of an associated item, returns any region
+    /// Given the `DefId` of an associated item, returns any region
     /// bounds attached to that associated item from the trait definition.
     ///
     /// For example:
@@ -262,7 +262,7 @@ impl<'cx, 'gcx, 'tcx> VerifyBoundCx<'cx, 'gcx, 'tcx> {
     /// }
     /// ```
     ///
-    /// If we were given the def-id of `Foo::Bar`, we would return
+    /// If we were given the `DefId` of `Foo::Bar`, we would return
     /// `'a`. You could then apply the substitutions from the
     /// projection to convert this into your namespace. This also
     /// works if the user writes `where <Self as Foo<'a>>::Bar: 'a` on

src/librustc/infer/region_constraints/mod.rs

@@ -1,4 +1,4 @@
-//! See README.md
+//! See `README.md`.
 
 use self::CombineMapType::*;
 use self::UndoLog::*;
@@ -108,16 +108,16 @@ pub struct RegionConstraintData<'tcx> {
     pub givens: FxHashSet<(Region<'tcx>, ty::RegionVid)>,
 }
 
-/// A constraint that influences the inference process.
+/// Represents a constraint that influences the inference process.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, PartialOrd, Ord)]
 pub enum Constraint<'tcx> {
-    /// One region variable is subregion of another
+    /// A region variable is a subregion of another.
     VarSubVar(RegionVid, RegionVid),
 
-    /// Concrete region is subregion of region variable
+    /// A concrete region is a subregion of region variable.
     RegSubVar(Region<'tcx>, RegionVid),
 
-    /// Region variable is subregion of concrete region. This does not
+    /// A region variable is a subregion of a concrete region. This does not
     /// directly affect inference, but instead is checked after
     /// inference is complete.
     VarSubReg(RegionVid, Region<'tcx>),
@@ -138,9 +138,9 @@ impl Constraint<'_> {
     }
 }
 
-/// VerifyGenericBound(T, _, R, RS): The parameter type `T` (or
+/// `VerifyGenericBound(T, _, R, RS)`: the parameter type `T` (or
 /// associated type) must outlive the region `R`. `T` is known to
-/// outlive `RS`. Therefore verify that `R <= RS[i]` for some
+/// outlive `RS`. Therefore, verify that `R <= RS[i]` for some
 /// `i`. Inference variables may be involved (but this verification
 /// step doesn't influence inference).
 #[derive(Debug, Clone)]
@@ -164,7 +164,7 @@ EnumTypeFoldableImpl! {
     }
 }
 
-/// Describes the things that some `GenericKind` value G is known to
+/// Describes the things that some `GenericKind` value `G` is known to
 /// outlive. Each variant of `VerifyBound` can be thought of as a
 /// function:
 ///
@@ -187,6 +187,7 @@ pub enum VerifyBound<'tcx> {
     /// following, where `G` is the generic for which this verify
     /// bound was created:
     ///
+    /// ```rust
     /// fn(min) -> bool {
     ///     if G == K {
     ///         B(min)
@@ -194,6 +195,7 @@ pub enum VerifyBound<'tcx> {
     ///         false
     ///     }
     /// }
+    /// ```
     ///
     /// In other words, if the generic `G` that we are checking is
     /// equal to `K`, then check the associated verify bound
@@ -202,14 +204,16 @@ pub enum VerifyBound<'tcx> {
     /// This is used when we have something in the environment that
     /// may or may not be relevant, depending on the region inference
     /// results. For example, we may have `where <T as
-    /// Trait<'a>>::Item: 'b` in our where clauses. If we are
+    /// Trait<'a>>::Item: 'b` in our where-clauses. If we are
     /// generating the verify-bound for `<T as Trait<'0>>::Item`, then
     /// this where-clause is only relevant if `'0` winds up inferred
     /// to `'a`.
     ///
     /// So we would compile to a verify-bound like
     ///
+    /// ```
     /// IfEq(<T as Trait<'a>>::Item, AnyRegion('a))
+    /// ```
     ///
     /// meaning, if the subject G is equal to `<T as Trait<'a>>::Item`
     /// (after inference), and `'a: min`, then `G: min`.
@@ -217,9 +221,11 @@ pub enum VerifyBound<'tcx> {
 
     /// Given a region `R`, expands to the function:
     ///
+    /// ```
     /// fn(min) -> bool {
     ///     R: min
     /// }
+    /// ```
     ///
     /// This is used when we can establish that `G: R` -- therefore,
     /// if `R: min`, then by transitivity `G: min`.
@@ -227,20 +233,23 @@ pub enum VerifyBound<'tcx> {
 
     /// Given a set of bounds `B`, expands to the function:
     ///
+    /// ```rust
     /// fn(min) -> bool {
     ///     exists (b in B) { b(min) }
     /// }
+    /// ```
     ///
     /// In other words, if we meet some bound in `B`, that suffices.
-    /// This is used when all the bounds in `B` are known to apply to
+    /// This is used when all the bounds in `B` are known to apply to `G`.
-    /// G.
     AnyBound(Vec<VerifyBound<'tcx>>),
 
     /// Given a set of bounds `B`, expands to the function:
     ///
+    /// ```rust
     /// fn(min) -> bool {
     ///     forall (b in B) { b(min) }
     /// }
+    /// ```
     ///
     /// In other words, if we meet *all* bounds in `B`, that suffices.
     /// This is used when *some* bound in `B` is known to suffice, but
@@ -256,19 +265,19 @@ struct TwoRegions<'tcx> {
 
 #[derive(Copy, Clone, PartialEq)]
 enum UndoLog<'tcx> {
-    /// We added `RegionVid`
+    /// We added `RegionVid`.
     AddVar(RegionVid),
 
-    /// We added the given `constraint`
+    /// We added the given `constraint`.
     AddConstraint(Constraint<'tcx>),
 
-    /// We added the given `verify`
+    /// We added the given `verify`.
     AddVerify(usize),
 
-    /// We added the given `given`
+    /// We added the given `given`.
     AddGiven(Region<'tcx>, ty::RegionVid),
 
-    /// We added a GLB/LUB "combination variable"
+    /// We added a GLB/LUB "combination variable".
     AddCombination(CombineMapType, TwoRegions<'tcx>),
 
     /// During skolemization, we sometimes purge entries from the undo
@@ -707,7 +716,7 @@ impl<'tcx> RegionConstraintCollector<'tcx> {
         }
     }
 
-    /// See `Verify::VerifyGenericBound`
+    /// See [`Verify::VerifyGenericBound`].
     pub fn verify_generic_bound(
         &mut self,
         origin: SubregionOrigin<'tcx>,
@@ -837,7 +846,7 @@ impl<'tcx> RegionConstraintCollector<'tcx> {
             }).collect()
     }
 
-    /// See [`RegionInference::region_constraints_added_in_snapshot`]
+    /// See [`RegionInference::region_constraints_added_in_snapshot`].
     pub fn region_constraints_added_in_snapshot(&self, mark: &RegionSnapshot) -> Option<bool> {
         self.undo_log[mark.length..]
             .iter()
@@ -925,7 +934,8 @@ impl<'a, 'gcx, 'tcx> VerifyBound<'tcx> {
 }
 
 impl<'tcx> RegionConstraintData<'tcx> {
-    /// True if this region constraint data contains no constraints.
+    /// Returns `true` if this region constraint data contains no constraints, and `false`
+    /// otherwise.
     pub fn is_empty(&self) -> bool {
         let RegionConstraintData {
             constraints,

src/librustc/infer/type_variable.rs

@@ -218,7 +218,7 @@ impl<'tcx> TypeVariableTable<'tcx> {
         self.sub_relations.find(vid)
     }
 
-    /// True if `a` and `b` have same "sub-root" (i.e., exists some
+    /// Returns `true` if `a` and `b` have same "sub-root" (i.e., exists some
     /// type X such that `forall i in {a, b}. (i <: X || X <: i)`.
     pub fn sub_unified(&mut self, a: ty::TyVid, b: ty::TyVid) -> bool {
         self.sub_root_var(a) == self.sub_root_var(b)
@@ -306,7 +306,7 @@ impl<'tcx> TypeVariableTable<'tcx> {
             .collect()
     }
 
-    /// Find the set of type variables that existed *before* `s`
+    /// Finds the set of type variables that existed *before* `s`
     /// but which have only been unified since `s` started, and
     /// return the types with which they were unified. So if we had
     /// a type variable `V0`, then we started the snapshot, then we