libs: doc comments

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

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

src/liballoc/collections/btree/set.rs

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

src/liballoc/collections/vec_deque.rs

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

src/liballoc/macros.rs

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

src/liballoc/raw_vec.rs

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

src/liballoc/rc.rs

@@ -512,7 +512,7 @@ impl<T: ?Sized> Rc<T> {
         this.strong()
     }
 
-    /// Returns true if there are no other `Rc` or [`Weak`][weak] pointers to
+    /// Returns `true` if there are no other `Rc` or [`Weak`][weak] pointers to
     /// this inner value.
     ///
     /// [weak]: struct.Weak.html
@@ -561,7 +561,7 @@ impl<T: ?Sized> Rc<T> {
 
     #[inline]
     #[stable(feature = "ptr_eq", since = "1.17.0")]
-    /// Returns true if the two `Rc`s point to the same value (not
+    /// Returns `true` if the two `Rc`s point to the same value (not
     /// just values that compare as equal).
     ///
     /// # Examples
@@ -1334,8 +1334,8 @@ impl<T: ?Sized> Weak<T> {
         })
     }
 
-    /// Return `None` when the pointer is dangling and there is no allocated `RcBox`,
-    /// i.e., this `Weak` was created by `Weak::new`
+    /// Returns `None` when the pointer is dangling and there is no allocated `RcBox`
+    /// (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
-    /// * transitive, a < b and b < c implies a < c. The same must hold for both == 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 `>`.
     ///
     /// 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 `false` otherwise.
+    /// Returns `true` if this `String` has a length of zero, and `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`,
-    /// i.e., this `Weak` was created by `Weak::new`
+    /// Returns `None` when the pointer is dangling and there is no allocated `ArcInner`,
+    /// (i.e., when this `Weak` was created by `Weak::new`).
     #[inline]
     fn inner(&self) -> Option<&ArcInner<T>> {
         if is_dangling(self.ptr) {
@@ -1202,7 +1202,7 @@ impl<T: ?Sized> Weak<T> {
         }
     }
 
-    /// Returns true if the two `Weak`s point to the same value (not just values
+    /// Returns `true` if the two `Weak`s point to the same value (not just values
     /// that compare as equal).
     ///
     /// # Notes

src/liballoc/tests/heap.rs

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

src/liballoc/vec.rs

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

src/libcore/cell.rs

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

src/libcore/char/decode.rs

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

src/libcore/char/methods.rs

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

src/libcore/default.rs

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

src/libcore/ffi.rs

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

src/libcore/fmt/mod.rs

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

src/libcore/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

@@ -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.
     ///
@@ -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
-    /// // with the following, transmute, way.
+    /// // There are multiple ways to do this, and there are multiple problems
+    /// // with the following (transmute) way.
     /// fn split_at_mut_transmute<T>(slice: &mut [T], mid: usize)
     ///                              -> (&mut [T], &mut [T]) {
     ///     let len = slice.len();
@@ -1200,19 +1200,19 @@ extern "rust-intrinsic" {
     /// unless size is equal to zero.
     pub fn volatile_set_memory<T>(dst: *mut T, val: u8, count: usize);
 
-    /// Perform a volatile load from the `src` pointer.
+    /// Performs a volatile load from the `src` pointer.
     /// The stabilized version of this intrinsic is
     /// [`std::ptr::read_volatile`](../../std/ptr/fn.read_volatile.html).
     pub fn volatile_load<T>(src: *const T) -> T;
-    /// Perform a volatile store to the `dst` pointer.
+    /// Performs a volatile store to the `dst` pointer.
     /// The stabilized version of this intrinsic is
     /// [`std::ptr::write_volatile`](../../std/ptr/fn.write_volatile.html).
     pub fn volatile_store<T>(dst: *mut T, val: T);
 
-    /// Perform a volatile load from the `src` pointer
+    /// Performs a volatile load from the `src` pointer
     /// The pointer is not required to be aligned.
     pub fn unaligned_volatile_load<T>(src: *const T) -> T;
-    /// Perform a volatile store to the `dst` pointer.
+    /// Performs a volatile store to the `dst` pointer.
     /// The pointer is not required to be aligned.
     pub fn unaligned_volatile_store<T>(dst: *mut T, val: T);
 

src/libcore/iter/range.rs

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

src/libcore/iter/traits/exact_size.rs

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

src/libcore/iter/traits/iterator.rs

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

src/libcore/macros.rs

@@ -1,4 +1,4 @@
-/// Entry point of thread panic, for details, see std::macros
+/// Entry point of thread panic. For details, see `std::macros`.
 #[macro_export]
 #[allow_internal_unstable]
 #[stable(feature = "core", since = "1.6.0")]
@@ -493,7 +493,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
-/// 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
+/// at their respective type. For example, a variable of reference type must
+/// be aligned and non-NULL. This is an invariant that must *always* be upheld,
+/// even in unsafe code. As a consequence, zero-initializing a variable of reference
 /// type causes instantaneous undefined behavior, no matter whether that reference
 /// ever gets used to access memory:
+///
 /// ```rust,no_run
 /// use std::mem;
 ///
 /// let x: &i32 = unsafe { mem::zeroed() }; // undefined behavior!
 /// ```
+///
 /// This is exploited by the compiler for various optimizations, such as eliding
 /// run-time checks and optimizing `enum` layout.
 ///
-/// Not initializing memory at all (instead of 0-initializing it) causes the same
+/// Not initializing memory at all (instead of zero--initializing it) causes the same
 /// issue: after all, the initial value of the variable might just happen to be
 /// one that violates the invariant.
 ///
 /// `MaybeUninit` serves to enable unsafe code to deal with uninitialized data:
 /// it is a signal to the compiler indicating that the data here might *not*
 /// be initialized:
+///
 /// ```rust
 /// #![feature(maybe_uninit)]
 /// use std::mem::MaybeUninit;
@@ -1070,6 +1073,7 @@ impl<T: ?Sized> DerefMut for ManuallyDrop<T> {
 /// // initializing `x`!
 /// let x = unsafe { x.into_initialized() };
 /// ```
+///
 /// The compiler then knows to not optimize this code.
 #[allow(missing_debug_implementations)]
 #[unstable(feature = "maybe_uninit", issue = "53491")]
@@ -1090,7 +1094,7 @@ impl<T> MaybeUninit<T> {
         MaybeUninit { value: ManuallyDrop::new(val) }
     }
 
-    /// Create a new `MaybeUninit` in an uninitialized state.
+    /// Creates a new `MaybeUninit` in an uninitialized state.
     ///
     /// Note that dropping a `MaybeUninit` will never call `T`'s drop code.
     /// It is your responsibility to make sure `T` gets dropped if it got initialized.
@@ -1100,7 +1104,7 @@ impl<T> MaybeUninit<T> {
         MaybeUninit { uninit: () }
     }
 
-    /// Create a new `MaybeUninit` in an uninitialized state, with the memory being
+    /// Creates a new `MaybeUninit` in an uninitialized state, with the memory being
     /// filled with `0` bytes. It depends on `T` whether that already makes for
     /// proper initialization. For example, `MaybeUninit<usize>::zeroed()` is initialized,
     /// but `MaybeUninit<&'static i32>::zeroed()` is not because references must not
@@ -1118,9 +1122,9 @@ impl<T> MaybeUninit<T> {
         u
     }
 
-    /// Set the value of the `MaybeUninit`. This overwrites any previous value without dropping it.
-    /// For your convenience, this also returns a mutable reference to the (now
-    /// safely initialized) content of `self`.
+    /// 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 safely initialized)
+    /// 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

@@ -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.
@@ -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

@@ -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
-    /// false otherwise.
+    /// Returns `true` if this value is positive infinity or negative infinity, and
+    /// `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
-    /// false otherwise.
+    /// Returns `true` if this value is positive infinity or negative infinity, and
+    /// `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> {

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

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

src/libcore/pin.rs

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

src/libcore/ptr.rs

@@ -825,7 +825,7 @@ pub unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
 ///
 /// The compiler shouldn't change the relative order or number of volatile
 /// memory operations. However, volatile memory operations on zero-sized types
-/// (e.g., if a zero-sized type is passed to `read_volatile`) are no-ops
+/// (e.g., if a zero-sized type is passed to `read_volatile`) are noops
 /// and may be ignored.
 ///
 /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
@@ -903,7 +903,7 @@ pub unsafe fn read_volatile<T>(src: *const T) -> T {
 ///
 /// The compiler shouldn't change the relative order or number of volatile
 /// memory operations. However, volatile memory operations on zero-sized types
-/// (e.g., if a zero-sized type is passed to `write_volatile`) are no-ops
+/// (e.g., if a zero-sized type is passed to `write_volatile`) are noops
 /// and may be ignored.
 ///
 /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
@@ -2473,7 +2473,7 @@ impl<T: ?Sized> PartialEq for *mut T {
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: ?Sized> Eq for *mut T {}
 
-/// Compare raw pointers for equality.
+/// Compares raw pointers for equality.
 ///
 /// This is the same as using the `==` operator, but less generic:
 /// the arguments have to be `*const T` raw pointers,

src/libcore/result.rs

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

src/libcore/slice/memchr.rs

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

src/libcore/slice/mod.rs

@@ -4123,7 +4123,7 @@ pub struct ChunksExact<'a, T:'a> {
 }
 
 impl<'a, T> ChunksExact<'a, T> {
-    /// Return the remainder of the original slice that is not going to be
+    /// Returns the remainder of the original slice that is not going to be
     /// returned by the iterator. The returned slice has at most `chunk_size-1`
     /// elements.
     #[stable(feature = "chunks_exact", since = "1.31.0")]
@@ -4247,7 +4247,7 @@ pub struct ChunksExactMut<'a, T:'a> {
 }
 
 impl<'a, T> ChunksExactMut<'a, T> {
-    /// Return the remainder of the original slice that is not going to be
+    /// Returns the remainder of the original slice that is not going to be
     /// returned by the iterator. The returned slice has at most `chunk_size-1`
     /// elements.
     #[stable(feature = "chunks_exact", since = "1.31.0")]
@@ -4619,7 +4619,7 @@ pub struct RChunksExact<'a, T:'a> {
 }
 
 impl<'a, T> RChunksExact<'a, T> {
-    /// Return the remainder of the original slice that is not going to be
+    /// Returns the remainder of the original slice that is not going to be
     /// returned by the iterator. The returned slice has at most `chunk_size-1`
     /// elements.
     #[stable(feature = "rchunks", since = "1.31.0")]
@@ -4744,7 +4744,7 @@ pub struct RChunksExactMut<'a, T:'a> {
 }
 
 impl<'a, T> RChunksExactMut<'a, T> {
-    /// Return the remainder of the original slice that is not going to be
+    /// Returns the remainder of the original slice that is not going to be
     /// returned by the iterator. The returned slice has at most `chunk_size-1`
     /// elements.
     #[stable(feature = "rchunks", since = "1.31.0")]

src/libcore/str/mod.rs

@@ -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.
@@ -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

@@ -117,7 +117,7 @@ pub unsafe trait Searcher<'a> {
     /// `[Reject(0, 1), Reject(1, 2), Match(2, 5), Reject(5, 8)]`
     fn next(&mut self) -> SearchStep;
 
-    /// Find the next `Match` result. See `next()`
+    /// Finds the next `Match` result. See `next()`
     ///
     /// Unlike next(), there is no guarantee that the returned ranges
     /// of this and next_reject will overlap. This will return (start_match, end_match),
@@ -134,7 +134,7 @@ pub unsafe trait Searcher<'a> {
         }
     }
 
-    /// Find the next `Reject` result. See `next()` and `next_match()`
+    /// Finds the next `Reject` result. See `next()` and `next_match()`
     ///
     /// Unlike next(), there is no guarantee that the returned ranges
     /// of this and next_match will overlap.
@@ -185,7 +185,7 @@ pub unsafe trait ReverseSearcher<'a>: Searcher<'a> {
     /// `[Reject(7, 8), Match(4, 7), Reject(1, 4), Reject(0, 1)]`
     fn next_back(&mut self) -> SearchStep;
 
-    /// Find the next `Match` result. See `next_back()`
+    /// Finds the next `Match` result. See `next_back()`
     #[inline]
     fn next_match_back(&mut self) -> Option<(usize, usize)>{
         loop {
@@ -197,7 +197,7 @@ pub unsafe trait ReverseSearcher<'a>: Searcher<'a> {
         }
     }
 
-    /// Find the next `Reject` result. See `next_back()`
+    /// Finds the next `Reject` result. See `next_back()`
     #[inline]
     fn next_reject_back(&mut self) -> Option<(usize, usize)>{
         loop {

src/libcore/task/poll.rs

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

src/libcore/task/wake.rs

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

src/libcore/tests/iter.rs

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

src/libcore/time.rs

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

src/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>

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

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()
     }

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();

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 {

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)

src/libstd/ffi/os_str.rs

@@ -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

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;
@@ -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

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

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

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`].
 //!

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

src/libstd/net/ip.rs

@@ -773,7 +773,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
     ///
@@ -791,7 +791,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
     ///
@@ -823,7 +823,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
     ///
@@ -1420,7 +1420,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
     ///
@@ -1448,7 +1448,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
     ///

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

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

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`.

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");
 /// ```
 ///

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]

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.

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

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();

src/libstd/sync/mpsc/select.rs

@@ -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 }
 

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

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

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

src/libstd/sync/rwlock.rs

@@ -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
     ///

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

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

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.

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)

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;

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

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>,

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> {

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
 }

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.

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() {

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

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

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.

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

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

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;

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>,

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;
 }

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.

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

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)

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