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/borrow.rs

@@ -137,11 +137,11 @@ impl<T> ToOwned for T
 /// ```
 /// use std::borrow::{Cow, ToOwned};
 ///
-/// struct Items<'a, X: 'a> where [X]: ToOwned<Owned=Vec<X>> {
+/// struct Items<'a, X: 'a> where [X]: ToOwned<Owned = Vec<X>> {
 ///     values: Cow<'a, [X]>,
 /// }
 ///
-/// impl<'a, X: Clone + 'a> Items<'a, X> where [X]: ToOwned<Owned=Vec<X>> {
+/// impl<'a, X: Clone + 'a> Items<'a, X> where [X]: ToOwned<Owned = Vec<X>> {
 ///     fn new(v: Cow<'a, [X]>) -> Self {
 ///         Items { values: v }
 ///     }

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

@@ -50,11 +50,11 @@ pub const CAPACITY: usize = 2 * B - 1;
 ///
 /// We have a separate type for the header and rely on it matching the prefix of `LeafNode`, in
 /// order to statically allocate a single dummy node to avoid allocations. This struct is
-/// `repr(C)` to prevent them from being reordered.  `LeafNode` does not just contain a
+/// `repr(C)` to prevent them from being reordered. `LeafNode` does not just contain a
 /// `NodeHeader` because we do not want unnecessary padding between `len` and the keys.
-/// Crucially, `NodeHeader` can be safely transmuted to different K and V.  (This is exploited
+/// Crucially, `NodeHeader` can be safely transmuted to different K and V. (This is exploited
 /// by `as_header`.)
-/// See `into_key_slice` for an explanation of K2.  K2 cannot be safely transmuted around
+/// See `into_key_slice` for an explanation of K2. K2 cannot be safely transmuted around
 /// because the size of `NodeHeader` depends on its alignment!
 #[repr(C)]
 struct NodeHeader<K, V, K2 = ()> {
@@ -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
     ///
@@ -1922,7 +1922,7 @@ impl<T> VecDeque<T> {
     ///
     /// # Panics
     ///
-    /// If `mid` is greater than `len()`.  Note that `mid == len()`
+    /// If `mid` is greater than `len()`. Note that `mid == len()`
     /// does _not_ panic and is a no-op rotation.
     ///
     /// # Complexity
@@ -1967,7 +1967,7 @@ impl<T> VecDeque<T> {
     ///
     /// # Panics
     ///
-    /// If `k` is greater than `len()`.  Note that `k == len()`
+    /// If `k` is greater than `len()`. Note that `k == len()`
     /// does _not_ panic and is a no-op rotation.
     ///
     /// # Complexity

src/liballoc/fmt.rs

@@ -27,7 +27,7 @@
 //! will then parse the format string and determine if the list of arguments
 //! provided is suitable to pass to this format string.
 //!
-//! To convert a single value to a string, use the [`to_string`] method.  This
+//! To convert a single value to a string, use the [`to_string`] method. This
 //! will use the [`Display`] formatting trait.
 //!
 //! ## Positional parameters
@@ -102,7 +102,7 @@
 //! When requesting that an argument be formatted with a particular type, you
 //! are actually requesting that an argument ascribes to a particular trait.
 //! This allows multiple actual types to be formatted via `{:x}` (like [`i8`] as
-//! well as [`isize`]).  The current mapping of types to traits is:
+//! well as [`isize`]). The current mapping of types to traits is:
 //!
 //! * *nothing* ⇒ [`Display`]
 //! * `?` ⇒ [`Debug`]
@@ -427,7 +427,7 @@
 //! 3. An asterisk `.*`:
 //!
 //!    `.*` means that this `{...}` is associated with *two* format inputs rather than one: the
-//!    first input holds the `usize` precision, and the second holds the value to print.  Note that
+//!    first input holds the `usize` precision, and the second holds the value to print. Note that
 //!    in this case, if one uses the format string `{<arg>:<spec>.*}`, then the `<arg>` part refers
 //!    to the *value* to print, and the `precision` must come in the input preceding `<arg>`.
 //!

src/liballoc/macros.rs

@@ -63,18 +63,18 @@ macro_rules! vec {
 
 /// Creates a `String` using interpolation of runtime expressions.
 ///
-/// The first argument `format!` receives is a format string.  This must be a string
+/// The first argument `format!` receives is a format string. This must be a string
-/// literal.  The power of the formatting string is in the `{}`s contained.
+/// literal. The power of the formatting string is in the `{}`s contained.
 ///
 /// 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,
 /// depending on the intended destination of the string.
 ///
-/// To convert a single value to a string, use the [`to_string`] method.  This
+/// To convert a single value to a string, use the [`to_string`] method. This
 /// will use the [`Display`] formatting trait.
 ///
 /// [fmt]: ../std/fmt/index.html

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
@@ -738,7 +738,7 @@ impl<T> Vec<T> {
     /// Forces the length of the vector to `new_len`.
     ///
     /// This is a low-level operation that maintains none of the normal
-    /// invariants of the type.  Normally changing the length of a vector
+    /// invariants of the type. Normally changing the length of a vector
     /// is done using one of the safe operations instead, such as
     /// [`truncate`], [`resize`], [`extend`], or [`clear`].
     ///
@@ -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/alloc.rs

@@ -425,7 +425,7 @@ impl fmt::Display for CannotReallocInPlace {
 /// The `GlobalAlloc` trait is an `unsafe` trait for a number of reasons, and
 /// implementors must ensure that they adhere to these contracts:
 ///
-/// * It's undefined behavior if global allocators unwind.  This restriction may
+/// * It's undefined behavior if global allocators unwind. This restriction may
 ///   be lifted in the future, but currently a panic from any of these
 ///   functions may lead to memory unsafety.
 ///

src/libcore/any.rs

@@ -18,7 +18,7 @@
 //!
 //! Consider a situation where we want to log out a value passed to a function.
 //! We know the value we're working on implements Debug, but we don't know its
-//! concrete type.  We want to give special treatment to certain types: in this
+//! concrete type. We want to give special treatment to certain types: in this
 //! case printing out the length of String values prior to their value.
 //! We don't know the concrete type of our value at compile time, so we need to
 //! use runtime reflection instead.
@@ -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>`.
 //!
@@ -1133,7 +1133,7 @@ impl<'b, T: ?Sized> Ref<'b, T> {
     /// The `RefCell` is already immutably borrowed, so this cannot fail.
     ///
     /// This is an associated function that needs to be used as
-    /// `Ref::clone(...)`.  A `Clone` implementation or a method would interfere
+    /// `Ref::clone(...)`. A `Clone` implementation or a method would interfere
     /// with the widespread use of `r.borrow().clone()` to clone the contents of
     /// a `RefCell`.
     #[stable(feature = "cell_extras", since = "1.15.0")]
@@ -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,13 +1217,13 @@ 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.
     ///
     /// This is an associated function that needs to be used as
-    /// `RefMut::map(...)`.  A method would interfere with methods of the same
+    /// `RefMut::map(...)`. A method would interfere with methods of the same
     /// name on the contents of a `RefCell` used through `Deref`.
     ///
     /// # Examples
@@ -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/cmp.rs

@@ -26,7 +26,7 @@ use self::Ordering::*;
 /// relations](http://en.wikipedia.org/wiki/Partial_equivalence_relation).
 ///
 /// This trait allows for partial equality, for types that do not have a full
-/// equivalence relation.  For example, in floating point numbers `NaN != NaN`,
+/// equivalence relation. For example, in floating point numbers `NaN != NaN`,
 /// so floating point types implement `PartialEq` but not `Eq`.
 ///
 /// Formally, the equality must be (for all `a`, `b` and `c`):

src/libcore/convert.rs

@@ -220,7 +220,7 @@ pub trait AsMut<T: ?Sized> {
 ///
 /// There is one exception to implementing `Into`, and it's kind of esoteric.
 /// If the destination type is not part of the current crate, and it uses a
-/// generic variable, then you can't implement `From` directly.  For example,
+/// generic variable, then you can't implement `From` directly. For example,
 /// take this crate:
 ///
 /// ```compile_fail

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/future/future.rs

@@ -60,7 +60,7 @@ pub trait Future {
     /// progress, meaning that each time the current task is woken up, it should
     /// actively re-`poll` pending futures that it still has an interest in.
     ///
-    /// The `poll` function is not called repeatedly in a tight loop-- instead,
+    /// The `poll` function is not called repeatedly in a tight loop -- instead,
     /// it should only be called when the future indicates that it is ready to
     /// make progress (by calling `wake()`). If you're familiar with the
     /// `poll(2)` or `select(2)` syscalls on Unix it's worth noting that futures

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();
@@ -988,7 +988,7 @@ extern "rust-intrinsic" {
     ///   beginning at `dst` with the same size.
     ///
     /// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of
-    /// whether `T` is [`Copy`].  If `T` is not [`Copy`], using *both* the values
+    /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values
     /// in the region beginning at `*src` and the region beginning at `*dst` can
     /// [violate memory safety][read-ownership].
     ///
@@ -1055,7 +1055,7 @@ extern "rust-intrinsic" {
     /// [`copy_nonoverlapping`] can be used instead.
     ///
     /// `copy` is semantically equivalent to C's [`memmove`], but with the argument
-    /// order swapped.  Copying takes place as if the bytes were copied from `src`
+    /// order swapped. Copying takes place as if the bytes were copied from `src`
     /// to a temporary array and then copied from the array to `dst`.
     ///
     /// [`copy_nonoverlapping`]: ./fn.copy_nonoverlapping.html
@@ -1072,7 +1072,7 @@ extern "rust-intrinsic" {
     /// * Both `src` and `dst` must be properly aligned.
     ///
     /// Like [`read`], `copy` creates a bitwise copy of `T`, regardless of
-    /// whether `T` is [`Copy`].  If `T` is not [`Copy`], using both the values
+    /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values
     /// in the region beginning at `*src` and the region beginning at `*dst` can
     /// [violate memory safety][read-ownership].
     ///
@@ -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());
     /// ```
@@ -564,9 +564,9 @@ pub trait Iterator {
     /// Calls a closure on each element of an iterator.
     ///
     /// This is equivalent to using a [`for`] loop on the iterator, although
-    /// `break` and `continue` are not possible from a closure.  It's generally
+    /// `break` and `continue` are not possible from a closure. It's generally
     /// more idiomatic to use a `for` loop, but `for_each` may be more legible
-    /// when processing items at the end of longer iterator chains.  In some
+    /// when processing items at the end of longer iterator chains. In some
     /// cases `for_each` may also be faster than a loop, because it will use
     /// internal iteration on adaptors like `Chain`.
     ///
@@ -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);
@@ -1515,7 +1515,7 @@ pub trait Iterator {
     /// is propagated back to the caller immediately (short-circuiting).
     ///
     /// The initial value is the value the accumulator will have on the first
-    /// call.  If applying the closure succeeded against every element of the
+    /// call. If applying the closure succeeded against every element of the
     /// iterator, `try_fold()` returns the final accumulator as success.
     ///
     /// Folding is useful whenever you have a collection of something, and want
@@ -1528,10 +1528,10 @@ pub trait Iterator {
     /// do something better than the default `for` loop implementation.
     ///
     /// In particular, try to have this call `try_fold()` on the internal parts
-    /// from which this iterator is composed.  If multiple calls are needed,
+    /// from which this iterator is composed. If multiple calls are needed,
     /// the `?` operator may be convenient for chaining the accumulator value
     /// along, but beware any invariants that need to be upheld before those
-    /// early returns.  This is a `&mut self` method, so iteration needs to be
+    /// early returns. This is a `&mut self` method, so iteration needs to be
     /// resumable after hitting an error here.
     ///
     /// # Examples

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)]
@@ -434,7 +434,7 @@ macro_rules! writeln {
 /// * Iterators that dynamically terminate.
 ///
 /// If the determination that the code is unreachable proves incorrect, the
-/// program immediately terminates with a [`panic!`].  The function [`unreachable_unchecked`],
+/// program immediately terminates with a [`panic!`]. The function [`unreachable_unchecked`],
 /// which belongs to the [`std::hint`] module, informs the compiler to
 /// optimize the code out of the release version entirely.
 ///
@@ -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.
     ///
@@ -1038,26 +1038,29 @@ impl<T: ?Sized> DerefMut for ManuallyDrop<T> {
 /// A newtype to construct uninitialized instances of `T`.
 ///
 /// The compiler, in general, assumes that variables are properly initialized
-/// at their respective type.  For example, a variable of reference type must
+/// 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,
+/// 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,8 +1104,8 @@ 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
+    /// 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
     /// be null.
@@ -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.
     ///
@@ -1145,7 +1149,7 @@ impl<T> MaybeUninit<T> {
         ManuallyDrop::into_inner(self.value)
     }
 
-    /// Deprecated alternative to `into_initialized`.  Will never get stabilized.
+    /// Deprecated alternative to `into_initialized`. Will never get stabilized.
     /// Exists only to transition stdsimd to `into_initialized`.
     #[inline(always)]
     #[allow(unused)]
@@ -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

@@ -37,7 +37,7 @@
 //!
 //! In addition, there are numerous helper functions that are used in the paper but not available
 //! in Rust (or at least in core). Our version is additionally complicated by the need to handle
-//! overflow and underflow and the desire to handle subnormal numbers.  Bellerophon and
+//! overflow and underflow and the desire to handle subnormal numbers. Bellerophon and
 //! Algorithm R have trouble with overflow, subnormals, and underflow. We conservatively switch to
 //! Algorithm M (with the modifications described in section 8 of the paper) well before the
 //! inputs get into the critical region.
@@ -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.
@@ -148,7 +148,7 @@ macro_rules! from_str_float_impl {
             /// # Return value
             ///
             /// `Err(ParseFloatError)` if the string did not represent a valid
-            /// number.  Otherwise, `Ok(n)` where `n` is the floating-point
+            /// number. Otherwise, `Ok(n)` where `n` is the floating-point
             /// number represented by `src`.
             #[inline]
             fn from_str(src: &str) -> Result<Self, ParseFloatError> {
@@ -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/ops/arith.rs

@@ -49,7 +49,7 @@
 /// }
 ///
 /// // Notice that the implementation uses the associated type `Output`.
-/// impl<T: Add<Output=T>> Add for Point<T> {
+/// impl<T: Add<Output = T>> Add for Point<T> {
 ///     type Output = Point<T>;
 ///
 ///     fn add(self, other: Point<T>) -> Point<T> {
@@ -157,7 +157,7 @@ add_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
 /// }
 ///
 /// // Notice that the implementation uses the associated type `Output`.
-/// impl<T: Sub<Output=T>> Sub for Point<T> {
+/// impl<T: Sub<Output = T>> Sub for Point<T> {
 ///     type Output = Point<T>;
 ///
 ///     fn sub(self, other: Point<T>) -> Point<T> {
@@ -518,7 +518,7 @@ pub trait Rem<RHS=Self> {
 
 macro_rules! rem_impl_integer {
     ($($t:ty)*) => ($(
-        /// This operation satisfies `n % d == n - (n / d) * d`.  The
+        /// This operation satisfies `n % d == n - (n / d) * d`. The
         /// result has the same sign as the left operand.
         #[stable(feature = "rust1", since = "1.0.0")]
         impl Rem for $t {

src/libcore/ops/range.rs

@@ -52,7 +52,7 @@ impl fmt::Debug for RangeFull {
 /// (`start..end`).
 ///
 /// The `Range` `start..end` contains all values with `x >= start` and
-/// `x < end`.  It is empty unless `start < end`.
+/// `x < end`. It is empty unless `start < end`.
 ///
 /// # Examples
 ///
@@ -297,7 +297,7 @@ impl<Idx: PartialOrd<Idx>> RangeTo<Idx> {
 /// A range bounded inclusively below and above (`start..=end`).
 ///
 /// The `RangeInclusive` `start..=end` contains all values with `x >= start`
-/// and `x <= end`.  It is empty unless `start <= end`.
+/// and `x <= end`. It is empty unless `start <= end`.
 ///
 /// This iterator is [fused], but the specific values of `start` and `end` after
 /// iteration has finished are **unspecified** other than that [`.is_empty()`]

src/libcore/ops/try.rs

@@ -1,7 +1,7 @@
 /// A trait for customizing the behavior of the `?` operator.
 ///
 /// A type implementing `Try` is one that has a canonical way to view it
-/// in terms of a success/failure dichotomy.  This trait allows both
+/// in terms of a success/failure dichotomy. This trait allows both
 /// extracting those success or failure values from an existing instance and
 /// creating a new instance from a success or failure value.
 #[unstable(feature = "try_trait", issue = "42327")]

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

@@ -12,7 +12,7 @@
 //! to access only a single value, in which case the documentation omits the size
 //! and implicitly assumes it to be `size_of::<T>()` bytes.
 //!
-//! The precise rules for validity are not determined yet.  The guarantees that are
+//! The precise rules for validity are not determined yet. The guarantees that are
 //! provided at this point are very minimal:
 //!
 //! * A [null] pointer is *never* valid, not even for accesses of [size zero][zst].
@@ -104,7 +104,7 @@ pub use intrinsics::write_bytes;
 ///
 /// * `to_drop` must be [valid] for reads.
 ///
-/// * `to_drop` must be properly aligned.  See the example below for how to drop
+/// * `to_drop` must be properly aligned. See the example below for how to drop
 ///   an unaligned pointer.
 ///
 /// Additionally, if `T` is not [`Copy`], using the pointed-to value after
@@ -135,7 +135,7 @@ pub use intrinsics::write_bytes;
 /// unsafe {
 ///     // Get a raw pointer to the last element in `v`.
 ///     let ptr = &mut v[1] as *mut _;
-///     // Shorten `v` to prevent the last item from being dropped.  We do that first,
+///     // Shorten `v` to prevent the last item from being dropped. We do that first,
 ///     // to prevent issues if the `drop_in_place` below panics.
 ///     v.set_len(1);
 ///     // Without a call `drop_in_place`, the last item would never be dropped,
@@ -531,7 +531,7 @@ pub unsafe fn replace<T>(dst: *mut T, mut src: T) -> T {
 ///
 /// `read` creates a bitwise copy of `T`, regardless of whether `T` is [`Copy`].
 /// If `T` is not [`Copy`], using both the returned value and the value at
-/// `*src` can violate memory safety.  Note that assigning to `*src` counts as a
+/// `*src` can violate memory safety. Note that assigning to `*src` counts as a
 /// use because it will attempt to drop the value at `*src`.
 ///
 /// [`write`] can be used to overwrite data without causing it to be dropped.
@@ -588,7 +588,7 @@ pub unsafe fn read<T>(src: *const T) -> T {
 /// * `src` must be [valid] for reads.
 ///
 /// Like [`read`], `read_unaligned` creates a bitwise copy of `T`, regardless of
-/// whether `T` is [`Copy`].  If `T` is not [`Copy`], using both the returned
+/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned
 /// value and the value at `*src` can [violate memory safety][read-ownership].
 ///
 /// Note that even if `T` has size `0`, the pointer must be non-NULL.
@@ -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
@@ -839,7 +839,7 @@ pub unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
 /// * `src` must be properly aligned.
 ///
 /// Like [`read`], `read_unaligned` creates a bitwise copy of `T`, regardless of
-/// whether `T` is [`Copy`].  If `T` is not [`Copy`], using both the returned
+/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned
 /// value and the value at `*src` can [violate memory safety][read-ownership].
 /// However, storing non-[`Copy`] types in volatile memory is almost certainly
 /// incorrect.
@@ -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
@@ -1093,7 +1093,7 @@ impl<T: ?Sized> *const T {
     /// unless `x` and `y` point into the same allocated object.
     ///
     /// Always use `.offset(count)` instead when possible, because `offset`
-    /// allows the compiler to optimize better.  If you need to cross object
+    /// allows the compiler to optimize better. If you need to cross object
     /// boundaries, cast the pointer to an integer and do the arithmetic there.
     ///
     /// # Examples
@@ -1712,7 +1712,7 @@ impl<T: ?Sized> *mut T {
     /// unless `x` and `y` point into the same allocated object.
     ///
     /// Always use `.offset(count)` instead when possible, because `offset`
-    /// allows the compiler to optimize better.  If you need to cross object
+    /// allows the compiler to optimize better. If you need to cross object
     /// boundaries, cast the pointer to an integer and do the arithmetic there.
     ///
     /// # Examples
@@ -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

@@ -1197,7 +1197,7 @@ impl<T> [T] {
 
     /// Returns an iterator over subslices separated by elements that match
     /// `pred` limited to returning at most `n` items. This starts at the end of
-    /// the slice and works backwards.  The matched element is not contained in
+    /// the slice and works backwards. The matched element is not contained in
     /// the subslices.
     ///
     /// The last element returned, if any, will contain the remainder of the
@@ -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/slice/rotate.rs

@@ -26,7 +26,7 @@ impl<T> RawArray<T> {
 }
 
 /// Rotates the range `[mid-left, mid+right)` such that the element at `mid`
-/// becomes the first element.  Equivalently, rotates the range `left`
+/// becomes the first element. Equivalently, rotates the range `left`
 /// elements to the left or `right` elements to the right.
 ///
 /// # Safety
@@ -36,10 +36,10 @@ impl<T> RawArray<T> {
 /// # Algorithm
 ///
 /// For longer rotations, swap the left-most `delta = min(left, right)`
-/// elements with the right-most `delta` elements.  LLVM vectorizes this,
+/// elements with the right-most `delta` elements. LLVM vectorizes this,
 /// which is profitable as we only reach this step for a "large enough"
-/// rotation.  Doing this puts `delta` elements on the larger side into the
+/// rotation. Doing this puts `delta` elements on the larger side into the
-/// correct position, leaving a smaller rotate problem.  Demonstration:
+/// correct position, leaving a smaller rotate problem. Demonstration:
 ///
 /// ```text
 /// [ 6 7 8 9 10 11 12 13 . 1 2 3 4 5 ]

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.
@@ -1579,9 +1579,9 @@ mod traits {
 
     /// Implements ordering of strings.
     ///
-    /// Strings are ordered  lexicographically by their byte values.  This orders Unicode code
+    /// Strings are ordered  lexicographically by their byte values. This orders Unicode code
-    /// points based on their positions in the code charts.  This is not necessarily the same as
+    /// points based on their positions in the code charts. This is not necessarily the same as
-    /// "alphabetical" order, which varies by language and locale.  Sorting strings according to
+    /// "alphabetical" order, which varies by language and locale. Sorting strings according to
     /// culturally-accepted standards requires locale-specific data that is outside the scope of
     /// the `str` type.
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -1607,9 +1607,9 @@ mod traits {
 
     /// Implements comparison operations on strings.
     ///
-    /// Strings are compared lexicographically by their byte values.  This compares Unicode code
+    /// Strings are compared lexicographically by their byte values. This compares Unicode code
-    /// points based on their positions in the code charts.  This is not necessarily the same as
+    /// points based on their positions in the code charts. This is not necessarily the same as
-    /// "alphabetical" order, which varies by language and locale.  Comparing strings according to
+    /// "alphabetical" order, which varies by language and locale. Comparing strings according to
     /// culturally-accepted standards requires locale-specific data that is outside the scope of
     /// the `str` type.
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -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

@@ -43,7 +43,7 @@ pub const NANOSECOND: Duration = Duration::from_nanos(1);
 /// timeouts.
 ///
 /// Each `Duration` is composed of a whole number of seconds and a fractional part
-/// represented in nanoseconds.  If the underlying system does not support
+/// represented in nanoseconds. If the underlying system does not support
 /// nanosecond-level precision, APIs binding a system timeout will typically round up
 /// the number of nanoseconds.
 ///
@@ -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/libgraphviz/lib.rs

@@ -393,7 +393,7 @@ impl<'a> Id<'a> {
     /// digit (i.e., the regular expression `[a-zA-Z_][a-zA-Z_0-9]*`).
     ///
     /// (Note: this format is a strict subset of the `ID` format
-    /// defined by the DOT language.  This function may change in the
+    /// defined by the DOT language. This function may change in the
     /// future to accept a broader subset, or the entirety, of DOT's
     /// `ID` format.)
     ///
@@ -530,7 +530,7 @@ impl<'a> LabelText<'a> {
     }
 
     /// Decomposes content into string suitable for making EscStr that
-    /// yields same content as self.  The result obeys the law
+    /// yields same content as self. The result obeys the law
     /// render(`lt`) == render(`EscStr(lt.pre_escaped_content())`) for
     /// all `lt: LabelText`.
     fn pre_escaped_content(self) -> Cow<'a, str> {

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
@@ -23,14 +23,14 @@
 //!
 //! In the search phase, the job of a personality routine is to examine
 //! exception object being thrown, and to decide whether it should be caught at
-//! that stack frame.  Once the handler frame has been identified, cleanup phase
+//! that stack frame. Once the handler frame has been identified, cleanup phase
 //! begins.
 //!
 //! In the cleanup phase, the unwinder invokes each personality routine again.
 //! This time it decides which (if any) cleanup code needs to be run for
-//! the current stack frame.  If so, the control is transferred to a special
+//! the current stack frame. If so, the control is transferred to a special
 //! branch in the function body, the "landing pad", which invokes destructors,
-//! frees memory, etc.  At the end of the landing pad, control is transferred
+//! frees memory, etc. At the end of the landing pad, control is transferred
 //! back to the unwinder and unwinding resumes.
 //!
 //! Once stack has been unwound down to the handler frame level, unwinding stops
@@ -39,7 +39,7 @@
 //! ## `eh_personality` and `eh_unwind_resume`
 //!
 //! These language items are used by the compiler when generating unwind info.
-//! The first one is the personality routine described above.  The second one
+//! The first one is the personality routine described above. The second one
 //! allows compilation target to customize the process of resuming unwind at the
 //! end of the landing pads. `eh_unwind_resume` is used only if
 //! `custom_unwind_resume` flag in the target options is set.

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,
@@ -117,7 +117,7 @@ impl<'this, 'tcx> NestedVisitorMap<'this, 'tcx> {
 }
 
 /// Each method of the Visitor trait is a hook to be potentially
-/// overridden.  Each method's default implementation recursively visits
+/// overridden. Each method's default implementation recursively visits
 /// the substructure of the input via the corresponding `walk` method;
 /// e.g., the `visit_mod` method by default calls `intravisit::walk_mod`.
 ///
@@ -129,7 +129,7 @@ impl<'this, 'tcx> NestedVisitorMap<'this, 'tcx> {
 /// on `visit_nested_item` for details on how to visit nested items.
 ///
 /// If you want to ensure that your code handles every variant
-/// explicitly, you need to override each method.  (And you also need
+/// explicitly, you need to override each method. (And you also need
 /// to monitor future changes to `Visitor` in case a new method with a
 /// new default implementation gets introduced.)
 pub trait Visitor<'v> : Sized {
@@ -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)
@@ -214,7 +214,7 @@ pub trait Visitor<'v> : Sized {
     }
 
     /// When invoking `visit_all_item_likes()`, you need to supply an
-    /// item-like visitor.  This method converts a "intra-visit"
+    /// item-like visitor. This method converts a "intra-visit"
     /// visitor into an item-like visitor that walks the entire tree.
     /// If you use this, you probably don't want to process the
     /// contents of nested item-like things, since the outer loop will

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.
@@ -274,10 +274,10 @@ enum ParenthesizedGenericArgs {
 }
 
 /// What to do when we encounter an **anonymous** lifetime
-/// reference. Anonymous lifetime references come in two flavors.  You
+/// reference. Anonymous lifetime references come in two flavors. You
 /// have implicit, or fully elided, references to lifetimes, like the
 /// one in `&T` or `Ref<T>`, and you have `'_` lifetimes, like `&'_ T`
-/// or `Ref<'_, T>`.  These often behave the same, but not always:
+/// or `Ref<'_, T>`. These often behave the same, but not always:
 ///
 /// - certain usages of implicit references are deprecated, like
 ///   `Ref<T>`, and we sometimes just give hard errors in those cases
@@ -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,9 +1,9 @@
 //! 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,
+//! things" (represented by `FnLike` instances) share. For example,
 //! all `FnLike` instances have a type signature (be it explicit or
-//! inferred).  And all `FnLike` instances have a body, i.e., the code
+//! inferred). And all `FnLike` instances have a body, i.e., the code
 //! that is run when the function-like thing it represents is invoked.
 //!
 //! With the above abstraction in place, one can treat the program

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
+//! 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

@@ -1,6 +1,6 @@
-//! A nice interface for working with the infcx.  The basic idea is to
+//! A nice interface for working with the infcx. The basic idea is to
 //! do `infcx.at(cause, param_env)`, which sets the "cause" of the
-//! operation as well as the surrounding parameter environment.  Then
+//! operation as well as the surrounding parameter environment. Then
 //! you can do something like `.sub(a, b)` or `.eq(a, b)` to create a
 //! subtype or equality relationship respectively. The first argument
 //! is always the "expected" output from the POV of diagnostics.
@@ -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

@@ -112,14 +112,14 @@ impl<'cx, 'gcx, 'tcx> InferCtxt<'cx, 'gcx, 'tcx> {
     }
 
     /// A hacky variant of `canonicalize_query` that does not
-    /// canonicalize `'static`.  Unfortunately, the existing leak
+    /// canonicalize `'static`. Unfortunately, the existing leak
     /// check treaks `'static` differently in some cases (see also
     /// #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

@@ -289,7 +289,7 @@ impl<'cx, 'gcx, 'tcx> InferCtxt<'cx, 'gcx, 'tcx> {
     ///
     /// This is only meant to be invoked as part of constructing an
     /// inference context at the start of a query (see
-    /// `InferCtxtBuilder::enter_with_canonical`).  It basically
+    /// `InferCtxtBuilder::enter_with_canonical`). It basically
     /// brings the canonical value "into scope" within your new infcx.
     ///
     /// At the end of processing, the substitution S (once
@@ -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>,
@@ -267,7 +267,7 @@ impl<'cx, 'gcx, 'tcx> InferCtxt<'cx, 'gcx, 'tcx> {
     ///   they should be ignored).
     /// - It **can happen** (though it rarely does currently) that
     ///   equating types and things will give rise to subobligations
-    ///   that must be processed.  In this case, those subobligations
+    ///   that must be processed. In this case, those subobligations
     ///   are propagated back in the return value.
     /// - Finally, the query result (of type `R`) is propagated back,
     ///   after applying the substitution `S`.
@@ -506,7 +506,7 @@ impl<'cx, 'gcx, 'tcx> InferCtxt<'cx, 'gcx, 'tcx> {
 
     /// Given a "guess" at the values for the canonical variables in
     /// the input, try to unify with the *actual* values found in the
-    /// query result.  Often, but not always, this is a no-op, because
+    /// query result. Often, but not always, this is a no-op, because
     /// we already found the mapping in the "guessing" step.
     ///
     /// See also: `query_response_substitution_guess`

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
@@ -310,7 +310,7 @@ struct Generalization<'tcx> {
     /// particular around 'bivariant' type parameters that are only
     /// constrained by a where-clause. As an example, imagine a type:
     ///
-    ///     struct Foo<A, B> where A: Iterator<Item=B> {
+    ///     struct Foo<A, B> where A: Iterator<Item = B> {
     ///         data: A
     ///     }
     ///
@@ -323,7 +323,7 @@ struct Generalization<'tcx> {
     /// <: ?C`, but no particular relationship between `?B` and `?D`
     /// (after all, we do not know the variance of the normalized form
     /// of `A::Item` with respect to `A`). If we do nothing else, this
-    /// may mean that `?D` goes unconstrained (as in #41677).  So, in
+    /// may mean that `?D` goes unconstrained (as in #41677). So, in
     /// this scenario where we create a new type variable in a
     /// bivariant context, we set the `needs_wf` flag to true. This
     /// will force the calling code to check that `WF(Foo<?C, ?D>)`

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 {