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!

57 files changed, 264 insertions, 259 deletions

diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs
index 91c4e990e00..beecfb1aa29 100644
--- a/src/libstd/collections/hash/map.rs
+++ b/src/libstd/collections/hash/map.rs
@@ -370,7 +370,7 @@ const DISPLACEMENT_THRESHOLD: usize = 128;
 /// }
 ///
 /// impl Viking {
-///     /// Create a new Viking.
+///     /// Creates a new Viking.
 ///     fn new(name: &str, country: &str) -> Viking {
 ///         Viking { name: name.to_string(), country: country.to_string() }
 ///     }
@@ -556,7 +556,7 @@ fn pop_internal<K, V>(starting_bucket: FullBucketMut<K, V>)
     (retkey, retval, gap.into_table())
 }
 
-/// Perform robin hood bucket stealing at the given `bucket`. You must
+/// Performs robin hood bucket stealing at the given `bucket`. You must
 /// also pass that bucket's displacement so we don't have to recalculate it.
 ///
 /// `hash`, `key`, and `val` are the elements to "robin hood" into the hashtable.
@@ -1214,7 +1214,7 @@ impl<K, V, S> HashMap<K, V, S>
         self.table.size()
     }
 
-    /// Returns true if the map contains no elements.
+    /// Returns `true` if the map contains no elements.
     ///
     /// # Examples
     ///
@@ -1332,7 +1332,7 @@ impl<K, V, S> HashMap<K, V, S>
         self.search(k).map(|bucket| bucket.into_refs())
     }
 
-    /// Returns true if the map contains a value for the specified key.
+    /// Returns `true` if the map contains a value for the specified key.
     ///
     /// The key may be any borrowed form of the map's key type, but
     /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for
@@ -1896,7 +1896,7 @@ impl<'a, K, V, S> RawEntryBuilderMut<'a, K, V, S>
     where S: BuildHasher,
           K: Eq + Hash,
 {
-    /// Create a `RawEntryMut` from the given key.
+    /// Creates a `RawEntryMut` from the given key.
     #[unstable(feature = "hash_raw_entry", issue = "56167")]
     pub fn from_key<Q: ?Sized>(self, k: &Q) -> RawEntryMut<'a, K, V, S>
         where K: Borrow<Q>,
@@ -1907,7 +1907,7 @@ impl<'a, K, V, S> RawEntryBuilderMut<'a, K, V, S>
         self.from_key_hashed_nocheck(hasher.finish(), k)
     }
 
-    /// Create a `RawEntryMut` from the given key and its hash.
+    /// Creates a `RawEntryMut` from the given key and its hash.
     #[inline]
     #[unstable(feature = "hash_raw_entry", issue = "56167")]
     pub fn from_key_hashed_nocheck<Q: ?Sized>(self, hash: u64, k: &Q) -> RawEntryMut<'a, K, V, S>
@@ -1939,7 +1939,7 @@ impl<'a, K, V, S> RawEntryBuilderMut<'a, K, V, S>
             }
         }
     }
-    /// Create a `RawEntryMut` from the given hash.
+    /// Creates a `RawEntryMut` from the given hash.
     #[inline]
     #[unstable(feature = "hash_raw_entry", issue = "56167")]
     pub fn from_hash<F>(self, hash: u64, is_match: F) -> RawEntryMut<'a, K, V, S>
diff --git a/src/libstd/collections/hash/set.rs b/src/libstd/collections/hash/set.rs
index c55dd049ec6..92e63df7c68 100644
--- a/src/libstd/collections/hash/set.rs
+++ b/src/libstd/collections/hash/set.rs
@@ -471,7 +471,7 @@ impl<T, S> HashSet<T, S>
         self.map.len()
     }
 
-    /// Returns true if the set contains no elements.
+    /// Returns `true` if the set contains no elements.
     ///
     /// # Examples
     ///
@@ -696,7 +696,7 @@ impl<T, S> HashSet<T, S>
         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, but
diff --git a/src/libstd/collections/hash/table.rs b/src/libstd/collections/hash/table.rs
index 28beb80612c..9446a80a55c 100644
--- a/src/libstd/collections/hash/table.rs
+++ b/src/libstd/collections/hash/table.rs
@@ -248,11 +248,11 @@ impl<K, V, M> FullBucket<K, V, M> {
     pub fn into_table(self) -> M {
         self.table
     }
-    /// Get the raw index.
+    /// Gets the raw index.
     pub fn index(&self) -> usize {
         self.raw.idx
     }
-    /// Get the raw bucket.
+    /// Gets the raw bucket.
     pub fn raw(&self) -> RawBucket<K, V> {
         self.raw
     }
@@ -270,7 +270,7 @@ impl<K, V, M> EmptyBucket<K, V, M> {
 }
 
 impl<K, V, M> Bucket<K, V, M> {
-    /// Get the raw index.
+    /// Gets the raw index.
     pub fn index(&self) -> usize {
         self.raw.idx
     }
@@ -503,7 +503,7 @@ impl<K, V, M: Deref<Target = RawTable<K, V>>> FullBucket<K, V, M> {
         }
     }
 
-    /// Get the distance between this bucket and the 'ideal' location
+    /// Gets the distance between this bucket and the 'ideal' location
     /// as determined by the key's hash stored in it.
     ///
     /// In the cited blog posts above, this is called the "distance to
@@ -839,12 +839,12 @@ impl<K, V> RawTable<K, V> {
         }
     }
 
-    /// Set the table tag
+    /// Sets the table tag.
     pub fn set_tag(&mut self, value: bool) {
         self.hashes.set_tag(value)
     }
 
-    /// Get the table tag
+    /// Gets the table tag.
     pub fn tag(&self) -> bool {
         self.hashes.tag()
     }
diff --git a/src/libstd/collections/mod.rs b/src/libstd/collections/mod.rs
index ef397283ca4..9ebeff48426 100644
--- a/src/libstd/collections/mod.rs
+++ b/src/libstd/collections/mod.rs
@@ -323,8 +323,8 @@
 //! // A client of the bar. They have a blood alcohol level.
 //! struct Person { blood_alcohol: f32 }
 //!
-//! // All the orders made to the bar, by client id.
-//! let orders = vec![1,2,1,2,3,4,1,2,2,3,4,1,1,1];
+//! // All the orders made to the bar, by client ID.
+//! let orders = vec![1, 2, 1, 2, 3, 4, 1, 2, 2, 3, 4, 1, 1, 1];
 //!
 //! // Our clients.
 //! let mut blood_alcohol = BTreeMap::new();
diff --git a/src/libstd/error.rs b/src/libstd/error.rs
index 50415d9aeb9..f792ff56179 100644
--- a/src/libstd/error.rs
+++ b/src/libstd/error.rs
@@ -195,7 +195,7 @@ pub trait Error: Debug + Display {
     #[stable(feature = "error_source", since = "1.30.0")]
     fn source(&self) -> Option<&(dyn Error + 'static)> { None }
 
-    /// Get the `TypeId` of `self`
+    /// Gets the `TypeId` of `self`
     #[doc(hidden)]
     #[stable(feature = "error_type_id", since = "1.34.0")]
     fn type_id(&self) -> TypeId where Self: 'static {
@@ -564,7 +564,7 @@ impl Error for char::ParseCharError {
 
 // copied from any.rs
 impl dyn Error + 'static {
-    /// Returns true if the boxed type is the same as `T`
+    /// Returns `true` if the boxed type is the same as `T`
     #[stable(feature = "error_downcast", since = "1.3.0")]
     #[inline]
     pub fn is<T: Error + 'static>(&self) -> bool {
diff --git a/src/libstd/f64.rs b/src/libstd/f64.rs
index 2e0383ccef5..7fa7b807519 100644
--- a/src/libstd/f64.rs
+++ b/src/libstd/f64.rs
@@ -250,7 +250,7 @@ impl f64 {
     /// Calculates the least nonnegative remainder of `self (mod rhs)`.
     ///
     /// In particular, the return value `r` satisfies `0.0 <= r < rhs.abs()` in
-    /// most cases.  However, due to a floating point round-off error it can
+    /// most cases. However, due to a floating point round-off error it can
     /// result in `r == rhs.abs()`, violating the mathematical definition, if
     /// `self` is much smaller than `rhs.abs()` in magnitude and `self < 0.0`.
     /// This result is not an element of the function's codomain, but it is the
diff --git a/src/libstd/ffi/c_str.rs b/src/libstd/ffi/c_str.rs
index 765452e0288..caf490a0277 100644
--- a/src/libstd/ffi/c_str.rs
+++ b/src/libstd/ffi/c_str.rs
@@ -377,7 +377,7 @@ impl CString {
     ///
     /// # Examples
     ///
-    /// Create a `CString`, pass ownership to an `extern` function (via raw pointer), then retake
+    /// Creates a `CString`, pass ownership to an `extern` function (via raw pointer), then retake
     /// ownership with `from_raw`:
     ///
     /// ```ignore (extern-declaration)
diff --git a/src/libstd/ffi/os_str.rs b/src/libstd/ffi/os_str.rs
index f8176892513..7dbf15cdc90 100644
--- a/src/libstd/ffi/os_str.rs
+++ b/src/libstd/ffi/os_str.rs
@@ -24,7 +24,7 @@ use sys_common::{AsInner, IntoInner, FromInner};
 ///
 /// `OsString` and [`OsStr`] bridge this gap by simultaneously representing Rust
 /// and platform-native string values, and in particular allowing a Rust string
-/// to be converted into an "OS" string with no cost if possible.  A consequence
+/// to be converted into an "OS" string with no cost if possible. A consequence
 /// of this is that `OsString` instances are *not* `NUL` terminated; in order
 /// to pass to e.g., Unix system call, you should create a [`CStr`].
 ///
@@ -259,7 +259,7 @@ impl OsString {
     /// 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.
     ///
     /// # Examples
diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs
index 3538816c112..f1e8619fc8f 100644
--- a/src/libstd/fs.rs
+++ b/src/libstd/fs.rs
@@ -25,7 +25,7 @@ use time::SystemTime;
 ///
 /// # Examples
 ///
-/// Create a new file and write bytes to it:
+/// Creates a new file and write bytes to it:
 ///
 /// ```no_run
 /// use std::fs::File;
@@ -222,7 +222,7 @@ fn initial_buffer_size(file: &File) -> usize {
 /// Read the entire contents of a file into a bytes vector.
 ///
 /// This is a convenience function for using [`File::open`] and [`read_to_end`]
-/// with fewer imports and without an intermediate variable.  It pre-allocates a
+/// with fewer imports and without an intermediate variable. It pre-allocates a
 /// buffer based on the file size when available, so it is generally faster than
 /// reading into a vector created with `Vec::new()`.
 ///
@@ -263,7 +263,7 @@ pub fn read<P: AsRef<Path>>(path: P) -> io::Result<Vec<u8>> {
 /// Read the entire contents of a file into a string.
 ///
 /// This is a convenience function for using [`File::open`] and [`read_to_string`]
-/// with fewer imports and without an intermediate variable.  It pre-allocates a
+/// with fewer imports and without an intermediate variable. It pre-allocates a
 /// buffer based on the file size when available, so it is generally faster than
 /// reading into a string created with `String::new()`.
 ///
@@ -488,13 +488,13 @@ impl File {
         self.inner.file_attr().map(Metadata)
     }
 
-    /// Create a new `File` instance that shares the same underlying file handle
+    /// Creates a new `File` instance that shares the same underlying file handle
     /// as the existing `File` instance. Reads, writes, and seeks will affect
     /// both `File` instances simultaneously.
     ///
     /// # Examples
     ///
-    /// Create two handles for a file named `foo.txt`:
+    /// Creates two handles for a file named `foo.txt`:
     ///
     /// ```no_run
     /// use std::fs::File;
@@ -896,7 +896,7 @@ impl Metadata {
         FileType(self.0.file_type())
     }
 
-    /// Returns whether this metadata is for a directory. The
+    /// Returns `true` if this metadata is for a directory. The
     /// result is mutually exclusive to the result of
     /// [`is_file`], and will be false for symlink metadata
     /// obtained from [`symlink_metadata`].
@@ -919,7 +919,7 @@ impl Metadata {
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn is_dir(&self) -> bool { self.file_type().is_dir() }
 
-    /// Returns whether this metadata is for a regular file. The
+    /// Returns `true` if this metadata is for a regular file. The
     /// result is mutually exclusive to the result of
     /// [`is_dir`], and will be false for symlink metadata
     /// obtained from [`symlink_metadata`].
@@ -1096,7 +1096,7 @@ impl AsInner<fs_imp::FileAttr> for Metadata {
 }
 
 impl Permissions {
-    /// Returns whether these permissions describe a readonly (unwritable) file.
+    /// Returns `true` if these permissions describe a readonly (unwritable) file.
     ///
     /// # Examples
     ///
@@ -1152,7 +1152,7 @@ impl Permissions {
 }
 
 impl FileType {
-    /// Test whether this file type represents a directory. The
+    /// Tests whether this file type represents a directory. The
     /// result is mutually exclusive to the results of
     /// [`is_file`] and [`is_symlink`]; only zero or one of these
     /// tests may pass.
@@ -1176,7 +1176,7 @@ impl FileType {
     #[stable(feature = "file_type", since = "1.1.0")]
     pub fn is_dir(&self) -> bool { self.0.is_dir() }
 
-    /// Test whether this file type represents a regular file.
+    /// Tests whether this file type represents a regular file.
     /// The result is  mutually exclusive to the results of
     /// [`is_dir`] and [`is_symlink`]; only zero or one of these
     /// tests may pass.
@@ -1200,7 +1200,7 @@ impl FileType {
     #[stable(feature = "file_type", since = "1.1.0")]
     pub fn is_file(&self) -> bool { self.0.is_file() }
 
-    /// Test whether this file type represents a symbolic link.
+    /// Tests whether this file type represents a symbolic link.
     /// The result is mutually exclusive to the results of
     /// [`is_dir`] and [`is_file`]; only zero or one of these
     /// tests may pass.
@@ -1209,7 +1209,7 @@ impl FileType {
     /// with the [`fs::symlink_metadata`] function and not the
     /// [`fs::metadata`] function. The [`fs::metadata`] function
     /// follows symbolic links, so [`is_symlink`] would always
-    /// return false for the target file.
+    /// return `false` for the target file.
     ///
     /// [`Metadata`]: struct.Metadata.html
     /// [`fs::metadata`]: fn.metadata.html
@@ -1290,7 +1290,7 @@ impl DirEntry {
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn path(&self) -> PathBuf { self.0.path() }
 
-    /// Return the metadata for the file that this entry points at.
+    /// Returns the metadata for the file that this entry points at.
     ///
     /// This function will not traverse symlinks if this entry points at a
     /// symlink.
@@ -1325,7 +1325,7 @@ impl DirEntry {
         self.0.metadata().map(Metadata)
     }
 
-    /// Return the file type for the file that this entry points at.
+    /// Returns the file type for the file that this entry points at.
     ///
     /// This function will not traverse symlinks if this entry points at a
     /// symlink.
@@ -2025,7 +2025,7 @@ impl DirBuilder {
         self
     }
 
-    /// Create the specified directory with the options configured in this
+    /// Creates the specified directory with the options configured in this
     /// builder.
     ///
     /// It is considered an error if the directory already exists unless
diff --git a/src/libstd/io/buffered.rs b/src/libstd/io/buffered.rs
index 056aa7c0c42..0615cd59db4 100644
--- a/src/libstd/io/buffered.rs
+++ b/src/libstd/io/buffered.rs
@@ -16,9 +16,9 @@ use memchr;
 /// the underlying [`Read`] and maintains an in-memory buffer of the results.
 ///
 /// `BufReader` can improve the speed of programs that make *small* and
-/// *repeated* read calls to the same file or network socket.  It does not
+/// *repeated* read calls to the same file or network socket. It does not
 /// help when reading very large amounts at once, or reading just one or a few
-/// times.  It also provides no advantage when reading from a source that is
+/// times. It also provides no advantage when reading from a source that is
 /// already in memory, like a `Vec<u8>`.
 ///
 /// [`Read`]: ../../std/io/trait.Read.html
@@ -331,9 +331,9 @@ impl<R: Seek> Seek for BufReader<R> {
 /// writer in large, infrequent batches.
 ///
 /// `BufWriter` can improve the speed of programs that make *small* and
-/// *repeated* write calls to the same file or network socket.  It does not
+/// *repeated* write calls to the same file or network socket. It does not
 /// help when writing very large amounts at once, or writing just one or a few
-/// times.  It also provides no advantage when writing to a destination that is
+/// times. It also provides no advantage when writing to a destination that is
 /// in memory, like a `Vec<u8>`.
 ///
 /// When the `BufWriter` is dropped, the contents of its buffer will be written
diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index 28a6fbd48cf..c0570ae60a1 100644
--- a/src/libstd/io/mod.rs
+++ b/src/libstd/io/mod.rs
@@ -1219,11 +1219,11 @@ pub trait Seek {
 #[derive(Copy, PartialEq, Eq, Clone, Debug)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub enum SeekFrom {
-    /// Set the offset to the provided number of bytes.
+    /// Sets the offset to the provided number of bytes.
     #[stable(feature = "rust1", since = "1.0.0")]
     Start(#[stable(feature = "rust1", since = "1.0.0")] u64),
 
-    /// Set the offset to the size of this object plus the specified number of
+    /// Sets the offset to the size of this object plus the specified number of
     /// bytes.
     ///
     /// It is possible to seek beyond the end of an object, but it's an error to
@@ -1231,7 +1231,7 @@ pub enum SeekFrom {
     #[stable(feature = "rust1", since = "1.0.0")]
     End(#[stable(feature = "rust1", since = "1.0.0")] i64),
 
-    /// Set the offset to the current position plus the specified number of
+    /// Sets the offset to the current position plus the specified number of
     /// bytes.
     ///
     /// It is possible to seek beyond the end of an object, but it's an error to
diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs
index a7ecee2d822..bef6bc92661 100644
--- a/src/libstd/keyword_docs.rs
+++ b/src/libstd/keyword_docs.rs
@@ -260,7 +260,7 @@ mod extern_keyword { }
 /// }
 ///
 /// fn generic_where<T>(x: T) -> T
-///     where T: std::ops::Add<Output=T> + Copy
+///     where T: std::ops::Add<Output = T> + Copy
 /// {
 ///     x + x + x
 /// }
@@ -289,7 +289,7 @@ mod fn_keyword { }
 /// `for` is primarily used in for-in-loops, but it has a few other pieces of syntactic uses such as
 /// `impl Trait for Type` (see [`impl`] for more info on that). for-in-loops, or to be more
 /// precise, iterator loops, are a simple syntactic sugar over an exceedingly common practice
-/// within Rust, which is to loop over an iterator until that iterator returns None (or `break`
+/// within Rust, which is to loop over an iterator until that iterator returns `None` (or `break`
 /// is called).
 ///
 /// ```rust
@@ -627,7 +627,7 @@ mod loop_keyword { }
 /// directly accessed and modified.
 ///
 /// Tuple structs are similar to regular structs, but its fields have no names. They are used like
-/// tuples, with deconstruction possible via `let TupleStruct(x, y) = foo;` syntax.  For accessing
+/// tuples, with deconstruction possible via `let TupleStruct(x, y) = foo;` syntax. For accessing
 /// individual variables, the same syntax is used as with regular tuples, namely `foo.0`, `foo.1`,
 /// etc, starting at zero.
 ///
diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs
index 8ecba3ecd68..63cf6b62145 100644
--- a/src/libstd/lib.rs
+++ b/src/libstd/lib.rs
@@ -7,7 +7,7 @@
 //! primitives](#primitives), [standard macros](#macros), [I/O] and
 //! [multithreading], among [many other things][other].
 //!
-//! `std` is available to all Rust crates by default. Therefore the
+//! `std` is available to all Rust crates by default. Therefore, the
 //! standard library can be accessed in [`use`] statements through the path
 //! `std`, as in [`use std::env`].
 //!
diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs
index 506b6d4e8e0..dfe3079bb6c 100644
--- a/src/libstd/macros.rs
+++ b/src/libstd/macros.rs
@@ -11,8 +11,8 @@
 /// an unrecoverable problem.
 ///
 /// This macro is the perfect way to assert conditions in example code and in
-/// tests.  `panic!` is closely tied with the `unwrap` method of both [`Option`]
-/// and [`Result`][runwrap] enums.  Both implementations call `panic!` when they are set
+/// tests. `panic!` is closely tied with the `unwrap` method of both [`Option`]
+/// and [`Result`][runwrap] enums. Both implementations call `panic!` when they are set
 /// to None or Err variants.
 ///
 /// This macro is used to inject panic into a Rust thread, causing the thread to
@@ -21,7 +21,7 @@
 /// is transmitted.
 ///
 /// [`Result`] enum is often a better solution for recovering from errors than
-/// using the `panic!` macro.  This macro should be used to avoid proceeding using
+/// using the `panic!` macro. This macro should be used to avoid proceeding using
 /// incorrect values, such as from external sources. Detailed information about
 /// error handling is found in the [book].
 ///
@@ -80,7 +80,7 @@ macro_rules! panic {
 /// necessary to use [`io::stdout().flush()`][flush] to ensure the output is emitted
 /// immediately.
 ///
-/// Use `print!` only for the primary output of your program.  Use
+/// Use `print!` only for the primary output of your program. Use
 /// [`eprint!`] instead to print error and progress messages.
 ///
 /// [`println!`]: ../std/macro.println.html
@@ -126,7 +126,7 @@ macro_rules! print {
 /// Use the [`format!`] syntax to write data to the standard output.
 /// See [`std::fmt`] for more information.
 ///
-/// Use `println!` only for the primary output of your program.  Use
+/// Use `println!` only for the primary output of your program. Use
 /// [`eprintln!`] instead to print error and progress messages.
 ///
 /// [`format!`]: ../std/macro.format.html
@@ -157,10 +157,10 @@ macro_rules! println {
 /// Macro for printing to the standard error.
 ///
 /// Equivalent to the [`print!`] macro, except that output goes to
-/// [`io::stderr`] instead of `io::stdout`.  See [`print!`] for
+/// [`io::stderr`] instead of `io::stdout`. See [`print!`] for
 /// example usage.
 ///
-/// Use `eprint!` only for error and progress messages.  Use `print!`
+/// Use `eprint!` only for error and progress messages. Use `print!`
 /// instead for the primary output of your program.
 ///
 /// [`io::stderr`]: ../std/io/struct.Stderr.html
@@ -186,10 +186,10 @@ macro_rules! eprint {
 /// Macro for printing to the standard error, with a newline.
 ///
 /// Equivalent to the [`println!`] macro, except that output goes to
-/// [`io::stderr`] instead of `io::stdout`.  See [`println!`] for
+/// [`io::stderr`] instead of `io::stdout`. See [`println!`] for
 /// example usage.
 ///
-/// Use `eprintln!` only for error and progress messages.  Use `println!`
+/// Use `eprintln!` only for error and progress messages. Use `println!`
 /// instead for the primary output of your program.
 ///
 /// [`io::stderr`]: ../std/io/struct.Stderr.html
@@ -468,16 +468,16 @@ mod builtin {
     /// The core macro for formatted string creation & output.
     ///
     /// This macro functions by taking a formatting string literal containing
-    /// `{}` for each additional argument passed.  `format_args!` prepares the
+    /// `{}` for each additional argument passed. `format_args!` prepares the
     /// additional parameters to ensure the output can be interpreted as a string
-    /// and canonicalizes the arguments into a single type.  Any value that implements
+    /// and canonicalizes the arguments into a single type. Any value that implements
     /// the [`Display`] trait can be passed to `format_args!`, as can any
     /// [`Debug`] implementation be passed to a `{:?}` within the formatting string.
     ///
     /// This macro produces a value of type [`fmt::Arguments`]. This value can be
     /// passed to the macros within [`std::fmt`] for performing useful redirection.
     /// All other formatting macros ([`format!`], [`write!`], [`println!`], etc) are
-    /// proxied through this one.  `format_args!`, unlike its derived macros, avoids
+    /// proxied through this one. `format_args!`, unlike its derived macros, avoids
     /// heap allocations.
     ///
     /// You can use the [`fmt::Arguments`] value that `format_args!` returns
@@ -560,7 +560,7 @@ mod builtin {
     /// If the named environment variable is present at compile time, this will
     /// expand into an expression of type `Option<&'static str>` whose value is
     /// `Some` of the value of the environment variable. If the environment
-    /// variable is not present, then this will expand to `None`.  See
+    /// variable is not present, then this will expand to `None`. See
     /// [`Option<T>`][option] for more information on this type.
     ///
     /// A compile time error is never emitted when using this macro regardless
@@ -910,7 +910,7 @@ mod builtin {
     /// # Custom Messages
     ///
     /// This macro has a second form, where a custom panic message can
-    /// be provided with or without arguments for formatting.  See [`std::fmt`]
+    /// be provided with or without arguments for formatting. See [`std::fmt`]
     /// for syntax for this form.
     ///
     /// [`panic!`]: macro.panic.html
diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs
index 8ace1127658..654ad64d97b 100644
--- a/src/libstd/net/addr.rs
+++ b/src/libstd/net/addr.rs
@@ -510,7 +510,7 @@ impl SocketAddrV6 {
         self.inner.sin6_scope_id
     }
 
-    /// Change the scope ID associated with this socket address.
+    /// Changes the scope ID associated with this socket address.
     ///
     /// See the [`scope_id`] method's documentation for more details.
     ///
@@ -671,7 +671,7 @@ impl hash::Hash for SocketAddrV6 {
 /// [`SocketAddr`] values.
 ///
 /// This trait is used for generic address resolution when constructing network
-/// objects.  By default it is implemented for the following types:
+/// objects. By default it is implemented for the following types:
 ///
 ///  * [`SocketAddr`]: [`to_socket_addrs`] is the identity function.
 ///
diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs
index 4e064672fbc..d19cc482c15 100644
--- a/src/libstd/net/ip.rs
+++ b/src/libstd/net/ip.rs
@@ -772,7 +772,7 @@ impl FromInner<c::in_addr> for Ipv4Addr {
 
 #[stable(feature = "ip_u32", since = "1.1.0")]
 impl From<Ipv4Addr> for u32 {
-    /// Convert an `Ipv4Addr` into a host byte order `u32`.
+    /// Converts an `Ipv4Addr` into a host byte order `u32`.
     ///
     /// # Examples
     ///
@@ -790,7 +790,7 @@ impl From<Ipv4Addr> for u32 {
 
 #[stable(feature = "ip_u32", since = "1.1.0")]
 impl From<u32> for Ipv4Addr {
-    /// Convert a host byte order `u32` into an `Ipv4Addr`.
+    /// Converts a host byte order `u32` into an `Ipv4Addr`.
     ///
     /// # Examples
     ///
@@ -822,7 +822,7 @@ impl From<[u8; 4]> for Ipv4Addr {
 
 #[stable(feature = "ip_from_slice", since = "1.17.0")]
 impl From<[u8; 4]> for IpAddr {
-    /// Create an `IpAddr::V4` from a four element byte array.
+    /// Creates an `IpAddr::V4` from a four element byte array.
     ///
     /// # Examples
     ///
@@ -1419,7 +1419,7 @@ impl From<[u16; 8]> for Ipv6Addr {
 
 #[stable(feature = "ip_from_slice", since = "1.17.0")]
 impl From<[u8; 16]> for IpAddr {
-    /// Create an `IpAddr::V6` from a sixteen element byte array.
+    /// Creates an `IpAddr::V6` from a sixteen element byte array.
     ///
     /// # Examples
     ///
@@ -1447,7 +1447,7 @@ impl From<[u8; 16]> for IpAddr {
 
 #[stable(feature = "ip_from_slice", since = "1.17.0")]
 impl From<[u16; 8]> for IpAddr {
-    /// Create an `IpAddr::V6` from an eight element 16-bit array.
+    /// Creates an `IpAddr::V6` from an eight element 16-bit array.
     ///
     /// # Examples
     ///
diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs
index 86ecb10edf2..c4b0cd0f17c 100644
--- a/src/libstd/net/tcp.rs
+++ b/src/libstd/net/tcp.rs
@@ -497,7 +497,7 @@ impl TcpStream {
         self.0.ttl()
     }
 
-    /// Get the value of the `SO_ERROR` option on this socket.
+    /// Gets the value of the `SO_ERROR` option on this socket.
     ///
     /// This will retrieve the stored error in the underlying socket, clearing
     /// the field in the process. This can be useful for checking errors between
@@ -636,7 +636,7 @@ impl TcpListener {
     ///
     /// # Examples
     ///
-    /// Create a TCP listener bound to `127.0.0.1:80`:
+    /// Creates a TCP listener bound to `127.0.0.1:80`:
     ///
     /// ```no_run
     /// use std::net::TcpListener;
@@ -644,7 +644,7 @@ impl TcpListener {
     /// let listener = TcpListener::bind("127.0.0.1:80").unwrap();
     /// ```
     ///
-    /// Create a TCP listener bound to `127.0.0.1:80`. If that fails, create a
+    /// Creates a TCP listener bound to `127.0.0.1:80`. If that fails, create a
     /// TCP listener bound to `127.0.0.1:443`:
     ///
     /// ```no_run
@@ -811,7 +811,7 @@ impl TcpListener {
         self.0.only_v6()
     }
 
-    /// Get the value of the `SO_ERROR` option on this socket.
+    /// Gets the value of the `SO_ERROR` option on this socket.
     ///
     /// This will retrieve the stored error in the underlying socket, clearing
     /// the field in the process. This can be useful for checking errors between
diff --git a/src/libstd/net/udp.rs b/src/libstd/net/udp.rs
index 83459946ba6..d49871ce7bd 100644
--- a/src/libstd/net/udp.rs
+++ b/src/libstd/net/udp.rs
@@ -69,7 +69,7 @@ impl UdpSocket {
     ///
     /// # Examples
     ///
-    /// Create a UDP socket bound to `127.0.0.1:3400`:
+    /// Creates a UDP socket bound to `127.0.0.1:3400`:
     ///
     /// ```no_run
     /// use std::net::UdpSocket;
@@ -77,7 +77,7 @@ impl UdpSocket {
     /// let socket = UdpSocket::bind("127.0.0.1:3400").expect("couldn't bind to address");
     /// ```
     ///
-    /// Create a UDP socket bound to `127.0.0.1:3400`. If the socket cannot be
+    /// Creates a UDP socket bound to `127.0.0.1:3400`. If the socket cannot be
     /// bound to that address, create a UDP socket bound to `127.0.0.1:3401`:
     ///
     /// ```no_run
@@ -158,7 +158,7 @@ impl UdpSocket {
     /// This will return an error when the IP version of the local socket
     /// does not match that returned from [`ToSocketAddrs`].
     ///
-    /// See <https://github.com/rust-lang/rust/issues/34202> for more details.
+    /// See issue #34202 for more details.
     ///
     /// [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html
     ///
@@ -590,7 +590,7 @@ impl UdpSocket {
         self.0.leave_multicast_v6(multiaddr, interface)
     }
 
-    /// Get the value of the `SO_ERROR` option on this socket.
+    /// Gets the value of the `SO_ERROR` option on this socket.
     ///
     /// This will retrieve the stored error in the underlying socket, clearing
     /// the field in the process. This can be useful for checking errors between
@@ -627,7 +627,7 @@ impl UdpSocket {
     ///
     /// # Examples
     ///
-    /// Create a UDP socket bound to `127.0.0.1:3400` and connect the socket to
+    /// Creates a UDP socket bound to `127.0.0.1:3400` and connect the socket to
     /// `127.0.0.1:8080`:
     ///
     /// ```no_run
@@ -756,7 +756,7 @@ impl UdpSocket {
     ///
     /// # Examples
     ///
-    /// Create a UDP socket bound to `127.0.0.1:7878` and read bytes in
+    /// Creates a UDP socket bound to `127.0.0.1:7878` and read bytes in
     /// nonblocking mode:
     ///
     /// ```no_run
diff --git a/src/libstd/path.rs b/src/libstd/path.rs
index 5c7bff70a0d..0f1d627fa1e 100644
--- a/src/libstd/path.rs
+++ b/src/libstd/path.rs
@@ -2393,7 +2393,7 @@ impl Path {
         fs::read_dir(self)
     }
 
-    /// Returns whether the path points at an existing entity.
+    /// Returns `true` if the path points at an existing entity.
     ///
     /// This function will traverse symbolic links to query information about the
     /// destination file. In case of broken symbolic links this will return `false`.
@@ -2419,7 +2419,7 @@ impl Path {
         fs::metadata(self).is_ok()
     }
 
-    /// Returns whether the path exists on disk and is pointing at a regular file.
+    /// Returns `true` if the path exists on disk and is pointing at a regular file.
     ///
     /// This function will traverse symbolic links to query information about the
     /// destination file. In case of broken symbolic links this will return `false`.
@@ -2448,7 +2448,7 @@ impl Path {
         fs::metadata(self).map(|m| m.is_file()).unwrap_or(false)
     }
 
-    /// Returns whether the path exists on disk and is pointing at a directory.
+    /// Returns `true` if the path exists on disk and is pointing at a directory.
     ///
     /// This function will traverse symbolic links to query information about the
     /// destination file. In case of broken symbolic links this will return `false`.
diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs
index c2751508ce0..6bb7f28efeb 100644
--- a/src/libstd/primitive_docs.rs
+++ b/src/libstd/primitive_docs.rs
@@ -126,7 +126,7 @@ mod prim_bool { }
 ///
 /// ```ignore (string-from-str-error-type-is-not-never-yet)
 /// #[feature(exhaustive_patterns)]
-/// // NOTE: This does not work today!
+/// // NOTE: this does not work today!
 /// let Ok(s) = String::from_str("hello");
 /// ```
 ///
@@ -1062,7 +1062,7 @@ mod prim_ref { }
 /// On top of that, function pointers can vary based on what ABI they use. This is achieved by
 /// adding the `extern` keyword to the type name, followed by the ABI in question. For example,
 /// `fn()` is different from `extern "C" fn()`, which itself is different from `extern "stdcall"
-/// fn()`, and so on for the various ABIs that Rust supports.  Non-`extern` functions have an ABI
+/// fn()`, and so on for the various ABIs that Rust supports. Non-`extern` functions have an ABI
 /// of `"Rust"`, and `extern` functions without an explicit ABI have an ABI of `"C"`. For more
 /// information, see [the nomicon's section on foreign calling conventions][nomicon-abi].
 ///
diff --git a/src/libstd/process.rs b/src/libstd/process.rs
index 1263ef82e48..a2ef85016d8 100644
--- a/src/libstd/process.rs
+++ b/src/libstd/process.rs
@@ -427,7 +427,7 @@ impl Command {
     /// The search path to be used may be controlled by setting the
     /// `PATH` environment variable on the Command,
     /// but this has some implementation limitations on Windows
-    /// (see <https://github.com/rust-lang/rust/issues/37519>).
+    /// (see issue #37519).
     ///
     /// # Examples
     ///
@@ -445,7 +445,7 @@ impl Command {
         Command { inner: imp::Command::new(program.as_ref()) }
     }
 
-    /// Add an argument to pass to the program.
+    /// Adds an argument to pass to the program.
     ///
     /// Only one argument can be passed per use. So instead of:
     ///
@@ -487,7 +487,7 @@ impl Command {
         self
     }
 
-    /// Add multiple arguments to pass to the program.
+    /// Adds multiple arguments to pass to the program.
     ///
     /// To pass a single argument see [`arg`].
     ///
@@ -540,7 +540,7 @@ impl Command {
         self
     }
 
-    /// Add or update multiple environment variable mappings.
+    /// Adds or updates multiple environment variable mappings.
     ///
     /// # Examples
     ///
@@ -1287,7 +1287,7 @@ impl Child {
     ///
     /// let mut command = Command::new("ls");
     /// if let Ok(child) = command.spawn() {
-    ///     println!("Child's id is {}", child.id());
+    ///     println!("Child's ID is {}", child.id());
     /// } else {
     ///     println!("ls command didn't start");
     /// }
@@ -1332,7 +1332,7 @@ impl Child {
     ///
     /// This function will not block the calling thread and will only
     /// check to see if the child process has exited or not. If the child has
-    /// exited then on Unix the process id is reaped. This function is
+    /// exited then on Unix the process ID is reaped. This function is
     /// guaranteed to repeatedly return a successful exit status so long as the
     /// child has already exited.
     ///
@@ -1979,7 +1979,7 @@ mod tests {
         }
     }
 
-    /// Test that process creation flags work by debugging a process.
+    /// Tests that process creation flags work by debugging a process.
     /// Other creation flags make it hard or impossible to detect
     /// behavioral changes in the process.
     #[test]
diff --git a/src/libstd/sync/barrier.rs b/src/libstd/sync/barrier.rs
index f248c721e9a..bc2e14d436a 100644
--- a/src/libstd/sync/barrier.rs
+++ b/src/libstd/sync/barrier.rs
@@ -159,7 +159,7 @@ impl fmt::Debug for BarrierWaitResult {
 }
 
 impl BarrierWaitResult {
-    /// Returns whether this thread from [`wait`] is the "leader thread".
+    /// Returns `true` if this thread from [`wait`] is the "leader thread".
     ///
     /// Only one thread will have `true` returned from their result, all other
     /// threads will have `false` returned.
diff --git a/src/libstd/sync/condvar.rs b/src/libstd/sync/condvar.rs
index 76887379106..036aff090ea 100644
--- a/src/libstd/sync/condvar.rs
+++ b/src/libstd/sync/condvar.rs
@@ -17,7 +17,7 @@ use time::{Duration, Instant};
 pub struct WaitTimeoutResult(bool);
 
 impl WaitTimeoutResult {
-    /// Returns whether the wait was known to have timed out.
+    /// Returns `true` if the wait was known to have timed out.
     ///
     /// # Examples
     ///
@@ -343,13 +343,13 @@ impl Condvar {
     ///
     /// Note that the best effort is made to ensure that the time waited is
     /// measured with a monotonic clock, and not affected by the changes made to
-    /// the system time.  This function is susceptible to spurious wakeups.
+    /// the system time. This function is susceptible to spurious wakeups.
     /// Condition variables normally have a boolean predicate associated with
     /// them, and the predicate must always be checked each time this function
-    /// returns to protect against spurious wakeups.  Additionally, it is
+    /// returns to protect against spurious wakeups. Additionally, it is
     /// typically desirable for the time-out to not exceed some duration in
     /// spite of spurious wakes, thus the sleep-duration is decremented by the
-    /// amount slept.  Alternatively, use the `wait_timeout_until` method
+    /// amount slept. Alternatively, use the `wait_timeout_until` method
     /// to wait until a condition is met with a total time-out regardless
     /// of spurious wakes.
     ///
@@ -413,7 +413,7 @@ impl Condvar {
     }
 
     /// Waits on this condition variable for a notification, timing out after a
-    /// specified duration.  Spurious wakes will not cause this function to
+    /// specified duration. Spurious wakes will not cause this function to
     /// return.
     ///
     /// The semantics of this function are equivalent to [`wait_until`] except
diff --git a/src/libstd/sync/mpsc/blocking.rs b/src/libstd/sync/mpsc/blocking.rs
index ae5a18adbb3..eaf09a16756 100644
--- a/src/libstd/sync/mpsc/blocking.rs
+++ b/src/libstd/sync/mpsc/blocking.rs
@@ -50,14 +50,14 @@ impl SignalToken {
         wake
     }
 
-    /// Convert to an unsafe usize value. Useful for storing in a pipe's state
+    /// Converts to an unsafe usize value. Useful for storing in a pipe's state
     /// flag.
     #[inline]
     pub unsafe fn cast_to_usize(self) -> usize {
         mem::transmute(self.inner)
     }
 
-    /// Convert from an unsafe usize value. Useful for retrieving a pipe's state
+    /// Converts from an unsafe usize value. Useful for retrieving a pipe's state
     /// flag.
     #[inline]
     pub unsafe fn cast_from_usize(signal_ptr: usize) -> SignalToken {
@@ -72,7 +72,7 @@ impl WaitToken {
         }
     }
 
-    /// Returns true if we wake up normally, false otherwise.
+    /// Returns `true` if we wake up normally.
     pub fn wait_max_until(self, end: Instant) -> bool {
         while !self.inner.woken.load(Ordering::SeqCst) {
             let now = Instant::now();
diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs
index a8843549b8a..5273345c6b4 100644
--- a/src/libstd/sync/mpsc/mod.rs
+++ b/src/libstd/sync/mpsc/mod.rs
@@ -792,7 +792,7 @@ impl<T> Sender<T> {
     /// where the corresponding receiver has already been deallocated. Note
     /// that a return value of [`Err`] means that the data will never be
     /// received, but a return value of [`Ok`] does *not* mean that the data
-    /// will be received.  It is possible for the corresponding receiver to
+    /// will be received. It is possible for the corresponding receiver to
     /// hang up immediately after this function returns [`Ok`].
     ///
     /// [`Err`]: ../../../std/result/enum.Result.html#variant.Err
diff --git a/src/libstd/sync/mpsc/select.rs b/src/libstd/sync/mpsc/select.rs
index e34fc5487cf..8f6f9818d5c 100644
--- a/src/libstd/sync/mpsc/select.rs
+++ b/src/libstd/sync/mpsc/select.rs
@@ -72,11 +72,11 @@ struct SelectInner {
 impl !marker::Send for Select {}
 
 /// A handle to a receiver which is currently a member of a `Select` set of
-/// receivers.  This handle is used to keep the receiver in the set as well as
+/// receivers. This handle is used to keep the receiver in the set as well as
 /// interact with the underlying receiver.
 pub struct Handle<'rx, T:Send+'rx> {
     /// The ID of this handle, used to compare against the return value of
-    /// `Select::wait()`
+    /// `Select::wait()`.
     id: usize,
     selector: *mut SelectInner,
     next: *mut Handle<'static, ()>,
@@ -148,7 +148,7 @@ impl Select {
     }
 
     /// Waits for an event on this receiver set. The returned value is *not* an
-    /// index, but rather an id. This id can be queried against any active
+    /// index, but rather an ID. This ID can be queried against any active
     /// `Handle` structures (each one has an `id` method). The handle with
     /// the matching `id` will have some sort of event available on it. The
     /// event could either be that data is available or the corresponding
@@ -251,7 +251,7 @@ impl Select {
 }
 
 impl<'rx, T: Send> Handle<'rx, T> {
-    /// Retrieves the id of this handle.
+    /// Retrieves the ID of this handle.
     #[inline]
     pub fn id(&self) -> usize { self.id }
 
diff --git a/src/libstd/sync/mpsc/shared.rs b/src/libstd/sync/mpsc/shared.rs
index af538b75b70..3da73ac0b82 100644
--- a/src/libstd/sync/mpsc/shared.rs
+++ b/src/libstd/sync/mpsc/shared.rs
@@ -1,4 +1,4 @@
-/// Shared channels
+/// Shared channels.
 ///
 /// This is the flavor of channels which are not necessarily optimized for any
 /// particular use case, but are the most general in how they are used. Shared
diff --git a/src/libstd/sync/mutex.rs b/src/libstd/sync/mutex.rs
index 59829db23cb..340dca7ce73 100644
--- a/src/libstd/sync/mutex.rs
+++ b/src/libstd/sync/mutex.rs
@@ -335,7 +335,7 @@ impl<T: ?Sized> Mutex<T> {
     /// Returns a mutable reference to the underlying data.
     ///
     /// Since this call borrows the `Mutex` mutably, no actual locking needs to
-    /// take place---the mutable borrow statically guarantees no locks exist.
+    /// take place -- the mutable borrow statically guarantees no locks exist.
     ///
     /// # Errors
     ///
diff --git a/src/libstd/sync/once.rs b/src/libstd/sync/once.rs
index fcab2ffe144..656389789d7 100644
--- a/src/libstd/sync/once.rs
+++ b/src/libstd/sync/once.rs
@@ -228,7 +228,7 @@ impl Once {
     /// result in an immediate panic. If `f` panics, the `Once` will remain
     /// in a poison state. If `f` does _not_ panic, the `Once` will no
     /// longer be in a poison state and all future calls to `call_once` or
-    /// `call_one_force` will no-op.
+    /// `call_one_force` will be no-ops.
     ///
     /// The closure `f` is yielded a [`OnceState`] structure which can be used
     /// to query the poison status of the `Once`.
@@ -279,7 +279,7 @@ impl Once {
         });
     }
 
-    /// Returns true if some `call_once` call has completed
+    /// Returns `true` if some `call_once` call has completed
     /// successfully. Specifically, `is_completed` will return false in
     /// the following situations:
     ///   * `call_once` was not called at all,
@@ -465,7 +465,7 @@ impl<'a> Drop for Finish<'a> {
 }
 
 impl OnceState {
-    /// Returns whether the associated [`Once`] was poisoned prior to the
+    /// Returns `true` if the associated [`Once`] was poisoned prior to the
     /// invocation of the closure passed to [`call_once_force`].
     ///
     /// [`call_once_force`]: struct.Once.html#method.call_once_force
diff --git a/src/libstd/sync/rwlock.rs b/src/libstd/sync/rwlock.rs
index 7fbe0b8c199..730362e2ac8 100644
--- a/src/libstd/sync/rwlock.rs
+++ b/src/libstd/sync/rwlock.rs
@@ -314,7 +314,7 @@ impl<T: ?Sized> RwLock<T> {
     /// Determines whether the lock is poisoned.
     ///
     /// If another thread is active, the lock can still become poisoned at any
-    /// time.  You should not trust a `false` value for program correctness
+    /// time. You should not trust a `false` value for program correctness
     /// without additional synchronization.
     ///
     /// # Examples
@@ -384,7 +384,7 @@ impl<T: ?Sized> RwLock<T> {
     /// Returns a mutable reference to the underlying data.
     ///
     /// Since this call borrows the `RwLock` mutably, no actual locking needs to
-    /// take place---the mutable borrow statically guarantees no locks exist.
+    /// take place -- the mutable borrow statically guarantees no locks exist.
     ///
     /// # Errors
     ///
diff --git a/src/libstd/sys/cloudabi/abi/cloudabi.rs b/src/libstd/sys/cloudabi/abi/cloudabi.rs
index 0bf8c2d5998..83d45b3547b 100644
--- a/src/libstd/sys/cloudabi/abi/cloudabi.rs
+++ b/src/libstd/sys/cloudabi/abi/cloudabi.rs
@@ -673,11 +673,11 @@ bitflags! {
   /// Methods of synchronizing memory with physical storage.
   #[repr(C)]
   pub struct msflags: u8 {
-    /// Perform asynchronous writes.
+    /// Performs asynchronous writes.
     const ASYNC      = 0x01;
-    /// Invalidate cached data.
+    /// Invalidates cached data.
     const INVALIDATE = 0x02;
-    /// Perform synchronous writes.
+    /// Performs synchronous writes.
     const SYNC       = 0x04;
   }
 }
@@ -1750,11 +1750,9 @@ fn tcb_layout_test_64() {
 
 /// Entry point for additionally created threads.
 ///
-/// **tid**:
-/// Thread ID of the current thread.
+/// `tid`: thread ID of the current thread.
 ///
-/// **aux**:
-/// Copy of the value stored in
+/// `aux`: copy of the value stored in
 /// [`threadattr.argument`](struct.threadattr.html#structfield.argument).
 pub type threadentry = unsafe extern "C" fn(
   tid: tid,
@@ -2590,7 +2588,7 @@ pub unsafe fn mem_map(addr_: *mut (), len_: usize, prot_: mprot, flags_: mflags,
   cloudabi_sys_mem_map(addr_, len_, prot_, flags_, fd_, off_, mem_)
 }
 
-/// Change the protection of a memory mapping.
+/// Changes the protection of a memory mapping.
 ///
 /// ## Parameters
 ///
@@ -2604,7 +2602,7 @@ pub unsafe fn mem_protect(mapping_: &mut [u8], prot_: mprot) -> errno {
   cloudabi_sys_mem_protect(mapping_.as_mut_ptr() as *mut (), mapping_.len(), prot_)
 }
 
-/// Synchronize a region of memory with its physical storage.
+/// Synchronizes a region of memory with its physical storage.
 ///
 /// ## Parameters
 ///
diff --git a/src/libstd/sys/mod.rs b/src/libstd/sys/mod.rs
index 99ef74179c2..0a56f4fad6d 100644
--- a/src/libstd/sys/mod.rs
+++ b/src/libstd/sys/mod.rs
@@ -1,4 +1,4 @@
-//! Platform-dependent platform abstraction
+//! Platform-dependent platform abstraction.
 //!
 //! The `std::sys` module is the abstracted interface through which
 //! `std` talks to the underlying operating system. It has different
diff --git a/src/libstd/sys/redox/ext/fs.rs b/src/libstd/sys/redox/ext/fs.rs
index 04edfd6851d..8b81273f201 100644
--- a/src/libstd/sys/redox/ext/fs.rs
+++ b/src/libstd/sys/redox/ext/fs.rs
@@ -117,7 +117,7 @@ pub trait OpenOptionsExt {
     #[stable(feature = "fs_ext", since = "1.1.0")]
     fn mode(&mut self, mode: u32) -> &mut Self;
 
-    /// Pass custom flags to the `flags` argument of `open`.
+    /// Passes custom flags to the `flags` argument of `open`.
     ///
     /// The bits that define the access mode are masked out with `O_ACCMODE`, to
     /// ensure they do not interfere with the access mode set by Rusts options.
@@ -287,9 +287,9 @@ impl FileTypeExt for fs::FileType {
 /// # Note
 ///
 /// On Windows, you must specify whether a symbolic link points to a file
-/// or directory.  Use `os::windows::fs::symlink_file` to create a
+/// or directory. Use `os::windows::fs::symlink_file` to create a
 /// symbolic link to a file, or `os::windows::fs::symlink_dir` to create a
-/// symbolic link to a directory.  Additionally, the process must have
+/// symbolic link to a directory. Additionally, the process must have
 /// `SeCreateSymbolicLinkPrivilege` in order to be able to create a
 /// symbolic link.
 ///
diff --git a/src/libstd/sys/redox/ext/net.rs b/src/libstd/sys/redox/ext/net.rs
index 76c68829b7f..7411b8e068f 100644
--- a/src/libstd/sys/redox/ext/net.rs
+++ b/src/libstd/sys/redox/ext/net.rs
@@ -60,7 +60,7 @@ impl SocketAddr {
         None
     }
 
-    /// Returns true if and only if the address is unnamed.
+    /// Returns `true` if the address is unnamed.
     ///
     /// # Examples
     ///
@@ -374,7 +374,7 @@ impl UnixStream {
     /// ```
     ///
     /// # Platform specific
-    /// On Redox this always returns None.
+    /// On Redox this always returns `None`.
     #[stable(feature = "unix_socket_redox", since = "1.29")]
     pub fn take_error(&self) -> io::Result<Option<io::Error>> {
         Ok(None)
@@ -635,7 +635,7 @@ impl UnixListener {
     /// ```
     ///
     /// # Platform specific
-    /// On Redox this always returns None.
+    /// On Redox this always returns `None`.
     #[stable(feature = "unix_socket_redox", since = "1.29")]
     pub fn take_error(&self) -> io::Result<Option<io::Error>> {
         Ok(None)
diff --git a/src/libstd/sys/redox/ext/process.rs b/src/libstd/sys/redox/ext/process.rs
index 941fba8755b..1dcc1169510 100644
--- a/src/libstd/sys/redox/ext/process.rs
+++ b/src/libstd/sys/redox/ext/process.rs
@@ -13,13 +13,13 @@ use sys_common::{AsInnerMut, AsInner, FromInner, IntoInner};
 /// [`process::Command`]: ../../../../std/process/struct.Command.html
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait CommandExt {
-    /// Sets the child process's user id. This translates to a
+    /// Sets the child process's user ID. This translates to a
     /// `setuid` call in the child process. Failure in the `setuid`
     /// call will cause the spawn to fail.
     #[stable(feature = "rust1", since = "1.0.0")]
     fn uid(&mut self, id: u32) -> &mut process::Command;
 
-    /// Similar to `uid`, but sets the group id of the child process. This has
+    /// Similar to `uid`, but sets the group ID of the child process. This has
     /// the same semantics as the `uid` field.
     #[stable(feature = "rust1", since = "1.0.0")]
     fn gid(&mut self, id: u32) -> &mut process::Command;
diff --git a/src/libstd/sys/redox/mutex.rs b/src/libstd/sys/redox/mutex.rs
index 42424da858f..bf39cc48591 100644
--- a/src/libstd/sys/redox/mutex.rs
+++ b/src/libstd/sys/redox/mutex.rs
@@ -50,7 +50,7 @@ pub struct Mutex {
 }
 
 impl Mutex {
-    /// Create a new mutex.
+    /// Creates a new mutex.
     pub const fn new() -> Self {
         Mutex {
             lock: UnsafeCell::new(0),
diff --git a/src/libstd/sys/redox/process.rs b/src/libstd/sys/redox/process.rs
index 4199ab98cf1..9e23c537f22 100644
--- a/src/libstd/sys/redox/process.rs
+++ b/src/libstd/sys/redox/process.rs
@@ -561,7 +561,7 @@ impl ExitCode {
     }
 }
 
-/// The unique id of the process (this should never be negative).
+/// The unique ID of the process (this should never be negative).
 pub struct Process {
     pid: usize,
     status: Option<ExitStatus>,
diff --git a/src/libstd/sys/redox/syscall/call.rs b/src/libstd/sys/redox/syscall/call.rs
index b9e2b476cec..b9abb48a8d3 100644
--- a/src/libstd/sys/redox/syscall/call.rs
+++ b/src/libstd/sys/redox/syscall/call.rs
@@ -25,7 +25,7 @@ pub unsafe fn brk(addr: usize) -> Result<usize> {
     syscall1(SYS_BRK, addr)
 }
 
-/// Change the process's working directory
+/// Changes the process's working directory.
 ///
 /// This function will attempt to set the process's working directory to `path`, which can be
 /// either a relative, scheme relative, or absolute path.
@@ -47,90 +47,90 @@ pub fn chmod<T: AsRef<[u8]>>(path: T, mode: usize) -> Result<usize> {
     unsafe { syscall3(SYS_CHMOD, path.as_ref().as_ptr() as usize, path.as_ref().len(), mode) }
 }
 
-/// Produce a fork of the current process, or a new process thread
+/// Produces a fork of the current process, or a new process thread.
 pub unsafe fn clone(flags: usize) -> Result<usize> {
     syscall1_clobber(SYS_CLONE, flags)
 }
 
-/// Close a file
+/// Closes a file.
 pub fn close(fd: usize) -> Result<usize> {
     unsafe { syscall1(SYS_CLOSE, fd) }
 }
 
-/// Get the current system time
+/// Gets the current system time.
 pub fn clock_gettime(clock: usize, tp: &mut TimeSpec) -> Result<usize> {
     unsafe { syscall2(SYS_CLOCK_GETTIME, clock, tp as *mut TimeSpec as usize) }
 }
 
-/// Copy and transform a file descriptor
+/// Copies and transforms a file descriptor.
 pub fn dup(fd: usize, buf: &[u8]) -> Result<usize> {
     unsafe { syscall3(SYS_DUP, fd, buf.as_ptr() as usize, buf.len()) }
 }
 
-/// Copy and transform a file descriptor
+/// Copies and transforms a file descriptor.
 pub fn dup2(fd: usize, newfd: usize, buf: &[u8]) -> Result<usize> {
     unsafe { syscall4(SYS_DUP2, fd, newfd, buf.as_ptr() as usize, buf.len()) }
 }
 
-/// Exit the current process
+/// Exits the current process.
 pub fn exit(status: usize) -> Result<usize> {
     unsafe { syscall1(SYS_EXIT, status) }
 }
 
-/// Change file permissions
+/// Changes file permissions.
 pub fn fchmod(fd: usize, mode: u16) -> Result<usize> {
     unsafe { syscall2(SYS_FCHMOD, fd, mode as usize) }
 
 }
 
-/// Change file ownership
+/// Changes file ownership.
 pub fn fchown(fd: usize, uid: u32, gid: u32) -> Result<usize> {
     unsafe { syscall3(SYS_FCHOWN, fd, uid as usize, gid as usize) }
 
 }
 
-/// Change file descriptor flags
+/// Changes file descriptor flags.
 pub fn fcntl(fd: usize, cmd: usize, arg: usize) -> Result<usize> {
     unsafe { syscall3(SYS_FCNTL, fd, cmd, arg) }
 }
 
-/// Replace the current process with a new executable
+/// Replaces the current process with a new executable.
 pub fn fexec(fd: usize, args: &[[usize; 2]], vars: &[[usize; 2]]) -> Result<usize> {
     unsafe { syscall5(SYS_FEXEC, fd, args.as_ptr() as usize, args.len(),
                       vars.as_ptr() as usize, vars.len()) }
 }
 
-/// Map a file into memory
+/// Maps a file into memory.
 pub unsafe fn fmap(fd: usize, offset: usize, size: usize) -> Result<usize> {
     syscall3(SYS_FMAP, fd, offset, size)
 }
 
-/// Unmap a memory-mapped file
+/// Unmaps a memory-mapped file.
 pub unsafe fn funmap(addr: usize) -> Result<usize> {
     syscall1(SYS_FUNMAP, addr)
 }
 
-/// Retrieve the canonical path of a file
+/// Retrieves the canonical path of a file.
 pub fn fpath(fd: usize, buf: &mut [u8]) -> Result<usize> {
     unsafe { syscall3(SYS_FPATH, fd, buf.as_mut_ptr() as usize, buf.len()) }
 }
 
-/// Rename a file
+/// Renames a file.
 pub fn frename<T: AsRef<[u8]>>(fd: usize, path: T) -> Result<usize> {
     unsafe { syscall3(SYS_FRENAME, fd, path.as_ref().as_ptr() as usize, path.as_ref().len()) }
 }
 
-/// Get metadata about a file
+/// Gets metadata about a file.
 pub fn fstat(fd: usize, stat: &mut Stat) -> Result<usize> {
     unsafe { syscall3(SYS_FSTAT, fd, stat as *mut Stat as usize, mem::size_of::<Stat>()) }
 }
 
-/// Get metadata about a filesystem
+/// Gets metadata about a filesystem.
 pub fn fstatvfs(fd: usize, stat: &mut StatVfs) -> Result<usize> {
     unsafe { syscall3(SYS_FSTATVFS, fd, stat as *mut StatVfs as usize, mem::size_of::<StatVfs>()) }
 }
 
-/// Sync a file descriptor to its underlying medium
+/// Syncs a file descriptor to its underlying medium.
 pub fn fsync(fd: usize) -> Result<usize> {
     unsafe { syscall1(SYS_FSYNC, fd) }
 }
@@ -152,113 +152,113 @@ pub unsafe fn futex(addr: *mut i32, op: usize, val: i32, val2: usize, addr2: *mu
     syscall5(SYS_FUTEX, addr as usize, op, (val as isize) as usize, val2, addr2 as usize)
 }
 
-/// Get the current working directory
+/// Gets the current working directory.
 pub fn getcwd(buf: &mut [u8]) -> Result<usize> {
     unsafe { syscall2(SYS_GETCWD, buf.as_mut_ptr() as usize, buf.len()) }
 }
 
-/// Get the effective group ID
+/// Gets the effective group ID.
 pub fn getegid() -> Result<usize> {
     unsafe { syscall0(SYS_GETEGID) }
 }
 
-/// Get the effective namespace
+/// Gets the effective namespace.
 pub fn getens() -> Result<usize> {
     unsafe { syscall0(SYS_GETENS) }
 }
 
-/// Get the effective user ID
+/// Gets the effective user ID.
 pub fn geteuid() -> Result<usize> {
     unsafe { syscall0(SYS_GETEUID) }
 }
 
-/// Get the current group ID
+/// Gets the current group ID.
 pub fn getgid() -> Result<usize> {
     unsafe { syscall0(SYS_GETGID) }
 }
 
-/// Get the current namespace
+/// Gets the current namespace.
 pub fn getns() -> Result<usize> {
     unsafe { syscall0(SYS_GETNS) }
 }
 
-/// Get the current process ID
+/// Gets the current process ID.
 pub fn getpid() -> Result<usize> {
     unsafe { syscall0(SYS_GETPID) }
 }
 
-/// Get the process group ID
+/// Gets the process group ID.
 pub fn getpgid(pid: usize) -> Result<usize> {
     unsafe { syscall1(SYS_GETPGID, pid) }
 }
 
-/// Get the parent process ID
+/// Gets the parent process ID.
 pub fn getppid() -> Result<usize> {
     unsafe { syscall0(SYS_GETPPID) }
 }
 
-/// Get the current user ID
+/// Gets the current user ID.
 pub fn getuid() -> Result<usize> {
     unsafe { syscall0(SYS_GETUID) }
 }
 
-/// Set the I/O privilege level
+/// Sets the I/O privilege level
 pub unsafe fn iopl(level: usize) -> Result<usize> {
     syscall1(SYS_IOPL, level)
 }
 
-/// Send a signal `sig` to the process identified by `pid`
+/// Sends a signal `sig` to the process identified by `pid`.
 pub fn kill(pid: usize, sig: usize) -> Result<usize> {
     unsafe { syscall2(SYS_KILL, pid, sig) }
 }
 
-/// Create a link to a file
+/// Creates a link to a file.
 pub unsafe fn link(old: *const u8, new: *const u8) -> Result<usize> {
     syscall2(SYS_LINK, old as usize, new as usize)
 }
 
-/// Seek to `offset` bytes in a file descriptor
+/// Seeks to `offset` bytes in a file descriptor.
 pub fn lseek(fd: usize, offset: isize, whence: usize) -> Result<usize> {
     unsafe { syscall3(SYS_LSEEK, fd, offset as usize, whence) }
 }
 
-/// Make a new scheme namespace
+/// Makes a new scheme namespace.
 pub fn mkns(schemes: &[[usize; 2]]) -> Result<usize> {
     unsafe { syscall2(SYS_MKNS, schemes.as_ptr() as usize, schemes.len()) }
 }
 
-/// Sleep for the time specified in `req`
+/// Sleeps for the time specified in `req`.
 pub fn nanosleep(req: &TimeSpec, rem: &mut TimeSpec) -> Result<usize> {
     unsafe { syscall2(SYS_NANOSLEEP, req as *const TimeSpec as usize,
                                      rem as *mut TimeSpec as usize) }
 }
 
-/// Open a file
+/// Opens a file.
 pub fn open<T: AsRef<[u8]>>(path: T, flags: usize) -> Result<usize> {
     unsafe { syscall3(SYS_OPEN, path.as_ref().as_ptr() as usize, path.as_ref().len(), flags) }
 }
 
-/// Allocate pages, linearly in physical memory
+/// Allocates pages, linearly in physical memory.
 pub unsafe fn physalloc(size: usize) -> Result<usize> {
     syscall1(SYS_PHYSALLOC, size)
 }
 
-/// Free physically allocated pages
+/// Frees physically allocated pages.
 pub unsafe fn physfree(physical_address: usize, size: usize) -> Result<usize> {
     syscall2(SYS_PHYSFREE, physical_address, size)
 }
 
-/// Map physical memory to virtual memory
+/// Maps physical memory to virtual memory.
 pub unsafe fn physmap(physical_address: usize, size: usize, flags: usize) -> Result<usize> {
     syscall3(SYS_PHYSMAP, physical_address, size, flags)
 }
 
-/// Unmap previously mapped physical memory
+/// Unmaps previously mapped physical memory.
 pub unsafe fn physunmap(virtual_address: usize) -> Result<usize> {
     syscall1(SYS_PHYSUNMAP, virtual_address)
 }
 
-/// Create a pair of file descriptors referencing the read and write ends of a pipe
+/// Creates a pair of file descriptors referencing the read and write ends of a pipe.
 pub fn pipe2(fds: &mut [usize; 2], flags: usize) -> Result<usize> {
     unsafe { syscall2(SYS_PIPE2, fds.as_ptr() as usize, flags) }
 }
@@ -268,32 +268,32 @@ pub fn read(fd: usize, buf: &mut [u8]) -> Result<usize> {
     unsafe { syscall3(SYS_READ, fd, buf.as_mut_ptr() as usize, buf.len()) }
 }
 
-/// Remove a directory
+/// Removes a directory.
 pub fn rmdir<T: AsRef<[u8]>>(path: T) -> Result<usize> {
     unsafe { syscall2(SYS_RMDIR, path.as_ref().as_ptr() as usize, path.as_ref().len()) }
 }
 
-/// Set the process group ID
+/// Sets the process group ID.
 pub fn setpgid(pid: usize, pgid: usize) -> Result<usize> {
     unsafe { syscall2(SYS_SETPGID, pid, pgid) }
 }
 
-/// Set the current process group IDs
+/// Sets the current process group IDs.
 pub fn setregid(rgid: usize, egid: usize) -> Result<usize> {
     unsafe { syscall2(SYS_SETREGID, rgid, egid) }
 }
 
-/// Make a new scheme namespace
+/// Makes a new scheme namespace.
 pub fn setrens(rns: usize, ens: usize) -> Result<usize> {
     unsafe { syscall2(SYS_SETRENS, rns, ens) }
 }
 
-/// Set the current process user IDs
+/// Sets the current process user IDs.
 pub fn setreuid(ruid: usize, euid: usize) -> Result<usize> {
     unsafe { syscall2(SYS_SETREUID, ruid, euid) }
 }
 
-/// Set up a signal handler
+/// Sets up a signal handler.
 pub fn sigaction(sig: usize, act: Option<&SigAction>, oldact: Option<&mut SigAction>)
 -> Result<usize> {
     unsafe { syscall4(SYS_SIGACTION, sig,
@@ -302,27 +302,27 @@ pub fn sigaction(sig: usize, act: Option<&SigAction>, oldact: Option<&mut SigAct
                       restorer as usize) }
 }
 
-// Return from signal handler
+/// Returns from signal handler.
 pub fn sigreturn() -> Result<usize> {
     unsafe { syscall0(SYS_SIGRETURN) }
 }
 
-/// Remove a file
+/// Removes a file.
 pub fn unlink<T: AsRef<[u8]>>(path: T) -> Result<usize> {
     unsafe { syscall2(SYS_UNLINK, path.as_ref().as_ptr() as usize, path.as_ref().len()) }
 }
 
-/// Convert a virtual address to a physical one
+/// Converts a virtual address to a physical one.
 pub unsafe fn virttophys(virtual_address: usize) -> Result<usize> {
     syscall1(SYS_VIRTTOPHYS, virtual_address)
 }
 
-/// Check if a child process has exited or received a signal
+/// Checks if a child process has exited or received a signal.
 pub fn waitpid(pid: usize, status: &mut usize, options: usize) -> Result<usize> {
     unsafe { syscall3(SYS_WAITPID, pid, status as *mut usize as usize, options) }
 }
 
-/// Write a buffer to a file descriptor
+/// Writes a buffer to a file descriptor.
 ///
 /// The kernel will attempt to write the bytes in `buf` to the file descriptor `fd`, returning
 /// either an `Err`, explained below, or `Ok(count)` where `count` is the number of bytes which
@@ -340,7 +340,7 @@ pub fn write(fd: usize, buf: &[u8]) -> Result<usize> {
     unsafe { syscall3(SYS_WRITE, fd, buf.as_ptr() as usize, buf.len()) }
 }
 
-/// Yield the process's time slice to the kernel
+/// Yields the process's time slice to the kernel.
 ///
 /// This function will return Ok(0) on success
 pub fn sched_yield() -> Result<usize> {
diff --git a/src/libstd/sys/redox/syscall/flag.rs b/src/libstd/sys/redox/syscall/flag.rs
index a41bc6d4a8b..5820f1ad03a 100644
--- a/src/libstd/sys/redox/syscall/flag.rs
+++ b/src/libstd/sys/redox/syscall/flag.rs
@@ -107,42 +107,42 @@ pub const WNOHANG: usize =    0x01;
 pub const WUNTRACED: usize =  0x02;
 pub const WCONTINUED: usize = 0x08;
 
-/// True if status indicates the child is stopped.
+/// Returns `true` if status indicates the child is stopped.
 pub fn wifstopped(status: usize) -> bool {
     (status & 0xff) == 0x7f
 }
 
-/// If wifstopped(status), the signal that stopped the child.
+/// If wifstopped(status), returns the signal that stopped the child.
 pub fn wstopsig(status: usize) -> usize {
     (status >> 8) & 0xff
 }
 
-/// True if status indicates the child continued after a stop.
+/// Returns `true` if status indicates the child continued after a stop.
 pub fn wifcontinued(status: usize) -> bool {
     status == 0xffff
 }
 
-/// True if STATUS indicates termination by a signal.
+/// Returns `true` if status indicates termination by a signal.
 pub fn wifsignaled(status: usize) -> bool {
     ((status & 0x7f) + 1) as i8 >= 2
 }
 
-/// If wifsignaled(status), the terminating signal.
+/// If wifsignaled(status), returns the terminating signal.
 pub fn wtermsig(status: usize) -> usize {
     status & 0x7f
 }
 
-/// True if status indicates normal termination.
+/// Returns `true` if status indicates normal termination.
 pub fn wifexited(status: usize) -> bool {
     wtermsig(status) == 0
 }
 
-/// If wifexited(status), the exit status.
+/// If wifexited(status), returns the exit status.
 pub fn wexitstatus(status: usize) -> usize {
     (status >> 8) & 0xff
 }
 
-/// True if status indicates a core dump was created.
+/// Returns `true` if status indicates a core dump was created.
 pub fn wcoredump(status: usize) -> bool {
     (status & 0x80) != 0
 }
diff --git a/src/libstd/sys/sgx/abi/thread.rs b/src/libstd/sys/sgx/abi/thread.rs
index 588fbcd9d43..86fe09d0035 100644
--- a/src/libstd/sys/sgx/abi/thread.rs
+++ b/src/libstd/sys/sgx/abi/thread.rs
@@ -1,6 +1,6 @@
 use fortanix_sgx_abi::Tcs;
 
-/// Get the ID for the current thread. The ID is guaranteed to be unique among
+/// Gets the ID for the current thread. The ID is guaranteed to be unique among
 /// all currently running threads in the enclave, and it is guaranteed to be
 /// constant for the lifetime of the thread. More specifically for SGX, there
 /// is a one-to-one correspondence of the ID to the address of the TCS.
diff --git a/src/libstd/sys/sgx/abi/tls.rs b/src/libstd/sys/sgx/abi/tls.rs
index b8e09d58deb..e1fc3696845 100644
--- a/src/libstd/sys/sgx/abi/tls.rs
+++ b/src/libstd/sys/sgx/abi/tls.rs
@@ -182,7 +182,7 @@ mod sync_bitset {
             self.0[hi].fetch_and(!lo, Ordering::Relaxed);
         }
 
-        /// Set any unset bit. Not atomic. Returns `None` if all bits were
+        /// Sets any unset bit. Not atomic. Returns `None` if all bits were
         /// observed to be set.
         pub fn set(&self) -> Option<usize> {
             'elems: for (idx, elem) in self.0.iter().enumerate() {
diff --git a/src/libstd/sys/sgx/abi/usercalls/alloc.rs b/src/libstd/sys/sgx/abi/usercalls/alloc.rs
index 2efbaa9b148..0ccbbbc6501 100644
--- a/src/libstd/sys/sgx/abi/usercalls/alloc.rs
+++ b/src/libstd/sys/sgx/abi/usercalls/alloc.rs
@@ -63,44 +63,49 @@ pub unsafe trait UserSafe {
 
     /// Construct a pointer to `Self` given a memory range in user space.
     ///
-    /// NB. This takes a size, not a length!
+    /// N.B., this takes a size, not a length!
     ///
     /// # Safety
+    ///
     /// The caller must ensure the memory range is in user memory, is the
     /// correct size and is correctly aligned and points to the right type.
     unsafe fn from_raw_sized_unchecked(ptr: *mut u8, size: usize) -> *mut Self;
 
     /// Construct a pointer to `Self` given a memory range.
     ///
-    /// NB. This takes a size, not a length!
+    /// N.B., this takes a size, not a length!
     ///
     /// # Safety
+    ///
     /// The caller must ensure the memory range points to the correct type.
     ///
     /// # Panics
+    ///
     /// This function panics if:
     ///
-    /// * The pointer is not aligned
-    /// * The pointer is null
-    /// * The pointed-to range is not in user memory
+    /// * the pointer is not aligned.
+    /// * the pointer is null.
+    /// * the pointed-to range is not in user memory.
     unsafe fn from_raw_sized(ptr: *mut u8, size: usize) -> NonNull<Self> {
         let ret = Self::from_raw_sized_unchecked(ptr, size);
         Self::check_ptr(ret);
         NonNull::new_unchecked(ret as _)
     }
 
-    /// Check if a pointer may point to Self in user memory.
+    /// Checks if a pointer may point to `Self` in user memory.
     ///
     /// # Safety
+    ///
     /// The caller must ensure the memory range points to the correct type and
     /// length (if this is a slice).
     ///
     /// # Panics
+    ///
     /// This function panics if:
     ///
-    /// * The pointer is not aligned
-    /// * The pointer is null
-    /// * The pointed-to range is not in user memory
+    /// * the pointer is not aligned.
+    /// * the pointer is null.
+    /// * the pointed-to range is not in user memory.
     unsafe fn check_ptr(ptr: *const Self) {
         let is_aligned = |p| -> bool {
             0 == (p as usize) & (Self::align_of() - 1)
@@ -188,7 +193,7 @@ impl<T: ?Sized> User<T> where T: UserSafe {
         }
     }
 
-    /// Copy `val` into freshly allocated space in user memory.
+    /// Copies `val` into freshly allocated space in user memory.
     pub fn new_from_enclave(val: &T) -> Self {
         unsafe {
             let ret = Self::new_uninit_bytes(mem::size_of_val(val));
@@ -201,7 +206,7 @@ impl<T: ?Sized> User<T> where T: UserSafe {
         }
     }
 
-    /// Create an owned `User<T>` from a raw pointer.
+    /// Creates an owned `User<T>` from a raw pointer.
     ///
     /// # Safety
     /// The caller must ensure `ptr` points to `T`, is freeable with the `free`
@@ -218,7 +223,7 @@ impl<T: ?Sized> User<T> where T: UserSafe {
         User(NonNull::new_userref(ptr))
     }
 
-    /// Convert this value into a raw pointer. The value will no longer be
+    /// Converts this value into a raw pointer. The value will no longer be
     /// automatically freed.
     pub fn into_raw(self) -> *mut T {
         let ret = self.0;
@@ -242,7 +247,7 @@ impl<T> User<[T]> where [T]: UserSafe {
         Self::new_uninit_bytes(n * mem::size_of::<T>())
     }
 
-    /// Create an owned `User<[T]>` from a raw thin pointer and a slice length.
+    /// Creates an owned `User<[T]>` from a raw thin pointer and a slice length.
     ///
     /// # Safety
     /// The caller must ensure `ptr` points to `len` elements of `T`, is
@@ -262,7 +267,7 @@ impl<T> User<[T]> where [T]: UserSafe {
 
 #[unstable(feature = "sgx_platform", issue = "56975")]
 impl<T: ?Sized> UserRef<T> where T: UserSafe {
-    /// Create a `&UserRef<[T]>` from a raw pointer.
+    /// Creates a `&UserRef<[T]>` from a raw pointer.
     ///
     /// # Safety
     /// The caller must ensure `ptr` points to `T`.
@@ -278,7 +283,7 @@ impl<T: ?Sized> UserRef<T> where T: UserSafe {
         &*(ptr as *const Self)
     }
 
-    /// Create a `&mut UserRef<[T]>` from a raw pointer. See the struct
+    /// Creates a `&mut UserRef<[T]>` from a raw pointer. See the struct
     /// documentation for the nuances regarding a `&mut UserRef<T>`.
     ///
     /// # Safety
@@ -295,7 +300,7 @@ impl<T: ?Sized> UserRef<T> where T: UserSafe {
         &mut*(ptr as *mut Self)
     }
 
-    /// Copy `val` into user memory.
+    /// Copies `val` into user memory.
     ///
     /// # Panics
     /// This function panics if the destination doesn't have the same size as
@@ -311,7 +316,7 @@ impl<T: ?Sized> UserRef<T> where T: UserSafe {
         }
     }
 
-    /// Copy the value from user memory and place it into `dest`.
+    /// Copies the value from user memory and place it into `dest`.
     ///
     /// # Panics
     /// This function panics if the destination doesn't have the same size as
@@ -340,7 +345,7 @@ impl<T: ?Sized> UserRef<T> where T: UserSafe {
 
 #[unstable(feature = "sgx_platform", issue = "56975")]
 impl<T> UserRef<T> where T: UserSafe {
-    /// Copy the value from user memory into enclave memory.
+    /// Copies the value from user memory into enclave memory.
     pub fn to_enclave(&self) -> T {
         unsafe { ptr::read(self.0.get()) }
     }
@@ -348,7 +353,7 @@ impl<T> UserRef<T> where T: UserSafe {
 
 #[unstable(feature = "sgx_platform", issue = "56975")]
 impl<T> UserRef<[T]> where [T]: UserSafe {
-    /// Create a `&UserRef<[T]>` from a raw thin pointer and a slice length.
+    /// Creates a `&UserRef<[T]>` from a raw thin pointer and a slice length.
     ///
     /// # Safety
     /// The caller must ensure `ptr` points to `n` elements of `T`.
@@ -363,7 +368,7 @@ impl<T> UserRef<[T]> where [T]: UserSafe {
         &*(<[T]>::from_raw_sized(ptr as _, len * mem::size_of::<T>()).as_ptr() as *const Self)
     }
 
-    /// Create a `&mut UserRef<[T]>` from a raw thin pointer and a slice length.
+    /// Creates a `&mut UserRef<[T]>` from a raw thin pointer and a slice length.
     /// See the struct documentation for the nuances regarding a
     /// `&mut UserRef<T>`.
     ///
@@ -395,7 +400,7 @@ impl<T> UserRef<[T]> where [T]: UserSafe {
         unsafe { (*self.0.get()).len() }
     }
 
-    /// Copy the value from user memory and place it into `dest`. Afterwards,
+    /// Copies the value from user memory and place it into `dest`. Afterwards,
     /// `dest` will contain exactly `self.len()` elements.
     ///
     /// # Panics
@@ -411,7 +416,7 @@ impl<T> UserRef<[T]> where [T]: UserSafe {
         }
     }
 
-    /// Copy the value from user memory into a vector in enclave memory.
+    /// Copies the value from user memory into a vector in enclave memory.
     pub fn to_enclave(&self) -> Vec<T> {
         let mut ret = Vec::with_capacity(self.len());
         self.copy_to_enclave_vec(&mut ret);
@@ -526,7 +531,7 @@ impl<T, I: SliceIndex<[T]>> IndexMut<I> for UserRef<[T]> where [T]: UserSafe, I:
 
 #[unstable(feature = "sgx_platform", issue = "56975")]
 impl UserRef<super::raw::ByteBuffer> {
-    /// Copy the user memory range pointed to by the user `ByteBuffer` to
+    /// Copies the user memory range pointed to by the user `ByteBuffer` to
     /// enclave memory.
     ///
     /// # Panics
diff --git a/src/libstd/sys/sgx/abi/usercalls/raw.rs b/src/libstd/sys/sgx/abi/usercalls/raw.rs
index 27f780ca224..004cf57602b 100644
--- a/src/libstd/sys/sgx/abi/usercalls/raw.rs
+++ b/src/libstd/sys/sgx/abi/usercalls/raw.rs
@@ -12,14 +12,16 @@ extern "C" {
     fn usercall(nr: u64, p1: u64, p2: u64, _ignore: u64, p3: u64, p4: u64) -> UsercallReturn;
 }
 
-/// Perform the raw usercall operation as defined in the ABI calling convention.
+/// Performs the raw usercall operation as defined in the ABI calling convention.
 ///
 /// # Safety
+///
 /// The caller must ensure to pass parameters appropriate for the usercall `nr`
 /// and to observe all requirements specified in the ABI.
 ///
 /// # Panics
-/// Panics if `nr` is 0.
+///
+/// Panics if `nr` is `0`.
 #[unstable(feature = "sgx_platform", issue = "56975")]
 pub unsafe fn do_usercall(nr: u64, p1: u64, p2: u64, p3: u64, p4: u64) -> (u64, u64) {
     if nr==0 { panic!("Invalid usercall number {}",nr) }
diff --git a/src/libstd/sys/sgx/waitqueue.rs b/src/libstd/sys/sgx/waitqueue.rs
index 51c00a1433e..aec643b3175 100644
--- a/src/libstd/sys/sgx/waitqueue.rs
+++ b/src/libstd/sys/sgx/waitqueue.rs
@@ -3,7 +3,7 @@
 /// This queue is used to implement condition variable and mutexes.
 ///
 /// Users of this API are expected to use the `WaitVariable<T>` type. Since
-/// that type is not `Sync`, it needs to be protected by e.g. a `SpinMutex` to
+/// that type is not `Sync`, it needs to be protected by e.g., a `SpinMutex` to
 /// allow shared access.
 ///
 /// Since userspace may send spurious wake-ups, the wakeup event state is
@@ -136,7 +136,7 @@ impl WaitQueue {
         self.inner.is_empty()
     }
 
-    /// Add the calling thread to the WaitVariable's wait queue, then wait
+    /// Adds the calling thread to the `WaitVariable`'s wait queue, then wait
     /// until a wakeup event.
     ///
     /// This function does not return until this thread has been awoken.
diff --git a/src/libstd/sys/unix/ext/fs.rs b/src/libstd/sys/unix/ext/fs.rs
index e962d09e274..abcce3ab829 100644
--- a/src/libstd/sys/unix/ext/fs.rs
+++ b/src/libstd/sys/unix/ext/fs.rs
@@ -684,7 +684,7 @@ impl MetadataExt for fs::Metadata {
 /// [`FileType`]: ../../../../std/fs/struct.FileType.html
 #[stable(feature = "file_type_ext", since = "1.5.0")]
 pub trait FileTypeExt {
-    /// Returns whether this file type is a block device.
+    /// Returns `true` if this file type is a block device.
     ///
     /// # Examples
     ///
@@ -702,7 +702,7 @@ pub trait FileTypeExt {
     /// ```
     #[stable(feature = "file_type_ext", since = "1.5.0")]
     fn is_block_device(&self) -> bool;
-    /// Returns whether this file type is a char device.
+    /// Returns `true` if this file type is a char device.
     ///
     /// # Examples
     ///
@@ -720,7 +720,7 @@ pub trait FileTypeExt {
     /// ```
     #[stable(feature = "file_type_ext", since = "1.5.0")]
     fn is_char_device(&self) -> bool;
-    /// Returns whether this file type is a fifo.
+    /// Returns `true` if this file type is a fifo.
     ///
     /// # Examples
     ///
@@ -738,7 +738,7 @@ pub trait FileTypeExt {
     /// ```
     #[stable(feature = "file_type_ext", since = "1.5.0")]
     fn is_fifo(&self) -> bool;
-    /// Returns whether this file type is a socket.
+    /// Returns `true` if this file type is a socket.
     ///
     /// # Examples
     ///
@@ -805,9 +805,9 @@ impl DirEntryExt for fs::DirEntry {
 /// # Note
 ///
 /// On Windows, you must specify whether a symbolic link points to a file
-/// or directory.  Use `os::windows::fs::symlink_file` to create a
+/// or directory. Use `os::windows::fs::symlink_file` to create a
 /// symbolic link to a file, or `os::windows::fs::symlink_dir` to create a
-/// symbolic link to a directory.  Additionally, the process must have
+/// symbolic link to a directory. Additionally, the process must have
 /// `SeCreateSymbolicLinkPrivilege` in order to be able to create a
 /// symbolic link.
 ///
diff --git a/src/libstd/sys/unix/ext/net.rs b/src/libstd/sys/unix/ext/net.rs
index a3ae5943f60..acc064acfcd 100644
--- a/src/libstd/sys/unix/ext/net.rs
+++ b/src/libstd/sys/unix/ext/net.rs
@@ -134,7 +134,7 @@ impl SocketAddr {
         })
     }
 
-    /// Returns true if and only if the address is unnamed.
+    /// Returns `true` if the address is unnamed.
     ///
     /// # Examples
     ///
@@ -516,7 +516,7 @@ impl UnixStream {
     /// ```
     ///
     /// # Platform specific
-    /// On Redox this always returns None.
+    /// On Redox this always returns `None`.
     #[stable(feature = "unix_socket", since = "1.10.0")]
     pub fn take_error(&self) -> io::Result<Option<io::Error>> {
         self.0.take_error()
@@ -841,7 +841,7 @@ impl UnixListener {
     /// ```
     ///
     /// # Platform specific
-    /// On Redox this always returns None.
+    /// On Redox this always returns `None`.
     #[stable(feature = "unix_socket", since = "1.10.0")]
     pub fn take_error(&self) -> io::Result<Option<io::Error>> {
         self.0.take_error()
@@ -1047,7 +1047,7 @@ impl UnixDatagram {
         Ok(UnixDatagram(inner))
     }
 
-    /// Create an unnamed pair of connected sockets.
+    /// Creates an unnamed pair of connected sockets.
     ///
     /// Returns two `UnixDatagrams`s which are connected to each other.
     ///
diff --git a/src/libstd/sys/unix/ext/process.rs b/src/libstd/sys/unix/ext/process.rs
index 0282aaae909..2c5943fdac3 100644
--- a/src/libstd/sys/unix/ext/process.rs
+++ b/src/libstd/sys/unix/ext/process.rs
@@ -13,13 +13,13 @@ use sys_common::{AsInnerMut, AsInner, FromInner, IntoInner};
 /// [`process::Command`]: ../../../../std/process/struct.Command.html
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait CommandExt {
-    /// Sets the child process's user id. This translates to a
+    /// Sets the child process's user ID. This translates to a
     /// `setuid` call in the child process. Failure in the `setuid`
     /// call will cause the spawn to fail.
     #[stable(feature = "rust1", since = "1.0.0")]
     fn uid(&mut self, id: u32) -> &mut process::Command;
 
-    /// Similar to `uid`, but sets the group id of the child process. This has
+    /// Similar to `uid`, but sets the group ID of the child process. This has
     /// the same semantics as the `uid` field.
     #[stable(feature = "rust1", since = "1.0.0")]
     fn gid(&mut self, id: u32) -> &mut process::Command;
diff --git a/src/libstd/sys/unix/process/process_unix.rs b/src/libstd/sys/unix/process/process_unix.rs
index f0f8032b4b5..12d3e9b13b1 100644
--- a/src/libstd/sys/unix/process/process_unix.rs
+++ b/src/libstd/sys/unix/process/process_unix.rs
@@ -383,7 +383,7 @@ impl Command {
 // Processes
 ////////////////////////////////////////////////////////////////////////////////
 
-/// The unique id of the process (this should never be negative).
+/// The unique ID of the process (this should never be negative).
 pub struct Process {
     pid: pid_t,
     status: Option<ExitStatus>,
diff --git a/src/libstd/sys/windows/ext/ffi.rs b/src/libstd/sys/windows/ext/ffi.rs
index eb278919307..6508c0cf447 100644
--- a/src/libstd/sys/windows/ext/ffi.rs
+++ b/src/libstd/sys/windows/ext/ffi.rs
@@ -3,19 +3,19 @@
 //! # Overview
 //!
 //! For historical reasons, the Windows API uses a form of potentially
-//! ill-formed UTF-16 encoding for strings.  Specifically, the 16-bit
+//! ill-formed UTF-16 encoding for strings. Specifically, the 16-bit
 //! code units in Windows strings may contain [isolated surrogate code
-//! points which are not paired together][ill-formed-utf-16].  The
+//! points which are not paired together][ill-formed-utf-16]. The
 //! Unicode standard requires that surrogate code points (those in the
 //! range U+D800 to U+DFFF) always be *paired*, because in the UTF-16
 //! encoding a *surrogate code unit pair* is used to encode a single
-//! character.  For compatibility with code that does not enforce
+//! character. For compatibility with code that does not enforce
 //! these pairings, Windows does not enforce them, either.
 //!
 //! While it is not always possible to convert such a string losslessly into
 //! a valid UTF-16 string (or even UTF-8), it is often desirable to be
 //! able to round-trip such a string from and to Windows APIs
-//! losslessly.  For example, some Rust code may be "bridging" some
+//! losslessly. For example, some Rust code may be "bridging" some
 //! Windows APIs together, just passing `WCHAR` strings among those
 //! APIs without ever really looking into the strings.
 //!
@@ -28,16 +28,16 @@
 //! # `OsStringExt` and `OsStrExt`
 //!
 //! [`OsString`] is the Rust wrapper for owned strings in the
-//! preferred representation of the operating system.  On Windows,
+//! preferred representation of the operating system. On Windows,
 //! this struct gets augmented with an implementation of the
-//! [`OsStringExt`] trait, which has a [`from_wide`] method.  This
+//! [`OsStringExt`] trait, which has a [`from_wide`] method. This
 //! lets you create an [`OsString`] from a `&[u16]` slice; presumably
 //! you get such a slice out of a `WCHAR` Windows API.
 //!
 //! Similarly, [`OsStr`] is the Rust wrapper for borrowed strings from
-//! preferred representation of the operating system.  On Windows, the
+//! preferred representation of the operating system. On Windows, the
 //! [`OsStrExt`] trait provides the [`encode_wide`] method, which
-//! outputs an [`EncodeWide`] iterator.  You can [`collect`] this
+//! outputs an [`EncodeWide`] iterator. You can [`collect`] this
 //! iterator, for example, to obtain a `Vec<u16>`; you can later get a
 //! pointer to this vector's contents and feed it to Windows APIs.
 //!
diff --git a/src/libstd/sys/windows/ext/fs.rs b/src/libstd/sys/windows/ext/fs.rs
index 6342af46daf..89038da6295 100644
--- a/src/libstd/sys/windows/ext/fs.rs
+++ b/src/libstd/sys/windows/ext/fs.rs
@@ -441,10 +441,10 @@ impl MetadataExt for Metadata {
 /// [`FileType`]: ../../../../std/fs/struct.FileType.html
 #[unstable(feature = "windows_file_type_ext", issue = "0")]
 pub trait FileTypeExt {
-    /// Returns whether this file type is a symbolic link that is also a directory.
+    /// Returns `true` if this file type is a symbolic link that is also a directory.
     #[unstable(feature = "windows_file_type_ext", issue = "0")]
     fn is_symlink_dir(&self) -> bool;
-    /// Returns whether this file type is a symbolic link that is also a file.
+    /// Returns `true` if this file type is a symbolic link that is also a file.
     #[unstable(feature = "windows_file_type_ext", issue = "0")]
     fn is_symlink_file(&self) -> bool;
 }
diff --git a/src/libstd/sys/windows/ext/io.rs b/src/libstd/sys/windows/ext/io.rs
index 76143dee464..fbe0426ce5a 100644
--- a/src/libstd/sys/windows/ext/io.rs
+++ b/src/libstd/sys/windows/ext/io.rs
@@ -16,7 +16,7 @@ pub type RawHandle = raw::HANDLE;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub type RawSocket = raw::SOCKET;
 
-/// Extract raw handles.
+/// Extracts raw handles.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait AsRawHandle {
     /// Extracts the raw handle, without taking any ownership.
@@ -98,7 +98,7 @@ impl IntoRawHandle for fs::File {
     }
 }
 
-/// Extract raw sockets.
+/// Extracts raw sockets.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait AsRawSocket {
     /// Extracts the underlying raw socket from this object.
@@ -106,7 +106,7 @@ pub trait AsRawSocket {
     fn as_raw_socket(&self) -> RawSocket;
 }
 
-/// Create I/O objects from raw sockets.
+/// Creates I/O objects from raw sockets.
 #[stable(feature = "from_raw_os", since = "1.1.0")]
 pub trait FromRawSocket {
     /// Creates a new I/O object from the given raw socket.
diff --git a/src/libstd/sys/windows/os.rs b/src/libstd/sys/windows/os.rs
index 5f478827b43..7399dd41a41 100644
--- a/src/libstd/sys/windows/os.rs
+++ b/src/libstd/sys/windows/os.rs
@@ -1,4 +1,4 @@
-//! Implementation of `std::os` functionality for Windows
+//! Implementation of `std::os` functionality for Windows.
 
 #![allow(nonstandard_style)]
 
diff --git a/src/libstd/sys/windows/pipe.rs b/src/libstd/sys/windows/pipe.rs
index 0d9195a5c97..d3b102268f6 100644
--- a/src/libstd/sys/windows/pipe.rs
+++ b/src/libstd/sys/windows/pipe.rs
@@ -282,7 +282,7 @@ impl<'a> AsyncPipe<'a> {
     /// Takes a parameter `wait` which indicates if this pipe is currently being
     /// read whether the function should block waiting for the read to complete.
     ///
-    /// Return values:
+    /// Returns values:
     ///
     /// * `true` - finished any pending read and the pipe is not at EOF (keep
     ///            going)
diff --git a/src/libstd/sys_common/backtrace.rs b/src/libstd/sys_common/backtrace.rs
index 57f31cb726c..347244b0e0d 100644
--- a/src/libstd/sys_common/backtrace.rs
+++ b/src/libstd/sys_common/backtrace.rs
@@ -171,7 +171,7 @@ pub fn log_enabled() -> Option<PrintFormat> {
     val
 }
 
-/// Print the symbol of the backtrace frame.
+/// Prints the symbol of the backtrace frame.
 ///
 /// These output functions should now be used everywhere to ensure consistency.
 /// You may want to also use `output_fileline`.
@@ -203,7 +203,7 @@ fn output(w: &mut dyn Write, idx: usize, frame: Frame,
     w.write_all(b"\n")
 }
 
-/// Print the filename and line number of the backtrace frame.
+/// Prints the filename and line number of the backtrace frame.
 ///
 /// See also `output`.
 #[allow(dead_code)]
diff --git a/src/libstd/sys_common/wtf8.rs b/src/libstd/sys_common/wtf8.rs
index 7f355fa7ec2..6d4594fe295 100644
--- a/src/libstd/sys_common/wtf8.rs
+++ b/src/libstd/sys_common/wtf8.rs
@@ -34,7 +34,7 @@ const UTF8_REPLACEMENT_CHARACTER: &str = "\u{FFFD}";
 
 /// A Unicode code point: from U+0000 to U+10FFFF.
 ///
-/// Compare with the `char` type,
+/// Compares with the `char` type,
 /// which represents a Unicode scalar value:
 /// a code point that is not a surrogate (U+D800 to U+DFFF).
 #[derive(Eq, PartialEq, Ord, PartialOrd, Clone, Copy)]
@@ -366,7 +366,7 @@ impl Wtf8Buf {
     }
 }
 
-/// Create a new WTF-8 string from an iterator of code points.
+/// Creates a new WTF-8 string from an iterator of code points.
 ///
 /// This replaces surrogate code point pairs with supplementary code points,
 /// like concatenating ill-formed UTF-16 strings effectively would.
@@ -664,7 +664,7 @@ impl Wtf8 {
 }
 
 
-/// Return a slice of the given string for the byte range [`begin`..`end`).
+/// Returns a slice of the given string for the byte range [`begin`..`end`).
 ///
 /// # Panics
 ///
@@ -686,7 +686,7 @@ impl ops::Index<ops::Range<usize>> for Wtf8 {
     }
 }
 
-/// Return a slice of the given string from byte `begin` to its end.
+/// Returns a slice of the given string from byte `begin` to its end.
 ///
 /// # Panics
 ///
@@ -706,7 +706,7 @@ impl ops::Index<ops::RangeFrom<usize>> for Wtf8 {
     }
 }
 
-/// Return a slice of the given string from its beginning to byte `end`.
+/// Returns a slice of the given string from its beginning to byte `end`.
 ///
 /// # Panics
 ///
diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs
index eb8e0c1c8ac..438ea3aa3f6 100644
--- a/src/libstd/thread/mod.rs
+++ b/src/libstd/thread/mod.rs
@@ -841,7 +841,7 @@ const NOTIFIED: usize = 2;
 /// let flag2 = Arc::clone(&flag);
 ///
 /// let parked_thread = thread::spawn(move || {
-///     // We want to wait until the flag is set.  We *could* just spin, but using
+///     // We want to wait until the flag is set. We *could* just spin, but using
 ///     // park/unpark is more efficient.
 ///     while !flag2.load(Ordering::Acquire) {
 ///         println!("Parking thread");
diff --git a/src/libstd/time.rs b/src/libstd/time.rs
index 23924559fcc..c258e3f1a55 100644
--- a/src/libstd/time.rs
+++ b/src/libstd/time.rs
@@ -33,7 +33,7 @@ pub use core::time::{SECOND, MILLISECOND, MICROSECOND, NANOSECOND};
 /// instant when created, and are often useful for tasks such as measuring
 /// benchmarks or timing how long an operation takes.
 ///
-/// Note, however, that instants are not guaranteed to be **steady**.  In other
+/// Note, however, that instants are not guaranteed to be **steady**. In other
 /// words, each tick of the underlying clock may not be the same length (e.g.
 /// some seconds may be longer than others). An instant may jump forwards or
 /// experience time dilation (slow down or speed up), but it will never go