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

Cosmetic improvements to doc comments

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

r? @steveklabnik

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

9 files changed, 21 insertions, 21 deletions

diff --git a/src/libstd/sync/barrier.rs b/src/libstd/sync/barrier.rs
index f248c721e9a..bc2e14d436a 100644
--- a/src/libstd/sync/barrier.rs
+++ b/src/libstd/sync/barrier.rs
@@ -159,7 +159,7 @@ impl fmt::Debug for BarrierWaitResult {
 }
 
 impl BarrierWaitResult {
-    /// Returns whether this thread from [`wait`] is the "leader thread".
+    /// Returns `true` if this thread from [`wait`] is the "leader thread".
     ///
     /// Only one thread will have `true` returned from their result, all other
     /// threads will have `false` returned.
diff --git a/src/libstd/sync/condvar.rs b/src/libstd/sync/condvar.rs
index 76887379106..036aff090ea 100644
--- a/src/libstd/sync/condvar.rs
+++ b/src/libstd/sync/condvar.rs
@@ -17,7 +17,7 @@ use time::{Duration, Instant};
 pub struct WaitTimeoutResult(bool);
 
 impl WaitTimeoutResult {
-    /// Returns whether the wait was known to have timed out.
+    /// Returns `true` if the wait was known to have timed out.
     ///
     /// # Examples
     ///
@@ -343,13 +343,13 @@ impl Condvar {
     ///
     /// Note that the best effort is made to ensure that the time waited is
     /// measured with a monotonic clock, and not affected by the changes made to
-    /// the system time.  This function is susceptible to spurious wakeups.
+    /// the system time. This function is susceptible to spurious wakeups.
     /// Condition variables normally have a boolean predicate associated with
     /// them, and the predicate must always be checked each time this function
-    /// returns to protect against spurious wakeups.  Additionally, it is
+    /// returns to protect against spurious wakeups. Additionally, it is
     /// typically desirable for the time-out to not exceed some duration in
     /// spite of spurious wakes, thus the sleep-duration is decremented by the
-    /// amount slept.  Alternatively, use the `wait_timeout_until` method
+    /// amount slept. Alternatively, use the `wait_timeout_until` method
     /// to wait until a condition is met with a total time-out regardless
     /// of spurious wakes.
     ///
@@ -413,7 +413,7 @@ impl Condvar {
     }
 
     /// Waits on this condition variable for a notification, timing out after a
-    /// specified duration.  Spurious wakes will not cause this function to
+    /// specified duration. Spurious wakes will not cause this function to
     /// return.
     ///
     /// The semantics of this function are equivalent to [`wait_until`] except
diff --git a/src/libstd/sync/mpsc/blocking.rs b/src/libstd/sync/mpsc/blocking.rs
index ae5a18adbb3..eaf09a16756 100644
--- a/src/libstd/sync/mpsc/blocking.rs
+++ b/src/libstd/sync/mpsc/blocking.rs
@@ -50,14 +50,14 @@ impl SignalToken {
         wake
     }
 
-    /// Convert to an unsafe usize value. Useful for storing in a pipe's state
+    /// Converts to an unsafe usize value. Useful for storing in a pipe's state
     /// flag.
     #[inline]
     pub unsafe fn cast_to_usize(self) -> usize {
         mem::transmute(self.inner)
     }
 
-    /// Convert from an unsafe usize value. Useful for retrieving a pipe's state
+    /// Converts from an unsafe usize value. Useful for retrieving a pipe's state
     /// flag.
     #[inline]
     pub unsafe fn cast_from_usize(signal_ptr: usize) -> SignalToken {
@@ -72,7 +72,7 @@ impl WaitToken {
         }
     }
 
-    /// Returns true if we wake up normally, false otherwise.
+    /// Returns `true` if we wake up normally.
     pub fn wait_max_until(self, end: Instant) -> bool {
         while !self.inner.woken.load(Ordering::SeqCst) {
             let now = Instant::now();
diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs
index a8843549b8a..5273345c6b4 100644
--- a/src/libstd/sync/mpsc/mod.rs
+++ b/src/libstd/sync/mpsc/mod.rs
@@ -792,7 +792,7 @@ impl<T> Sender<T> {
     /// where the corresponding receiver has already been deallocated. Note
     /// that a return value of [`Err`] means that the data will never be
     /// received, but a return value of [`Ok`] does *not* mean that the data
-    /// will be received.  It is possible for the corresponding receiver to
+    /// will be received. It is possible for the corresponding receiver to
     /// hang up immediately after this function returns [`Ok`].
     ///
     /// [`Err`]: ../../../std/result/enum.Result.html#variant.Err
diff --git a/src/libstd/sync/mpsc/select.rs b/src/libstd/sync/mpsc/select.rs
index e34fc5487cf..8f6f9818d5c 100644
--- a/src/libstd/sync/mpsc/select.rs
+++ b/src/libstd/sync/mpsc/select.rs
@@ -72,11 +72,11 @@ struct SelectInner {
 impl !marker::Send for Select {}
 
 /// A handle to a receiver which is currently a member of a `Select` set of
-/// receivers.  This handle is used to keep the receiver in the set as well as
+/// receivers. This handle is used to keep the receiver in the set as well as
 /// interact with the underlying receiver.
 pub struct Handle<'rx, T:Send+'rx> {
     /// The ID of this handle, used to compare against the return value of
-    /// `Select::wait()`
+    /// `Select::wait()`.
     id: usize,
     selector: *mut SelectInner,
     next: *mut Handle<'static, ()>,
@@ -148,7 +148,7 @@ impl Select {
     }
 
     /// Waits for an event on this receiver set. The returned value is *not* an
-    /// index, but rather an id. This id can be queried against any active
+    /// index, but rather an ID. This ID can be queried against any active
     /// `Handle` structures (each one has an `id` method). The handle with
     /// the matching `id` will have some sort of event available on it. The
     /// event could either be that data is available or the corresponding
@@ -251,7 +251,7 @@ impl Select {
 }
 
 impl<'rx, T: Send> Handle<'rx, T> {
-    /// Retrieves the id of this handle.
+    /// Retrieves the ID of this handle.
     #[inline]
     pub fn id(&self) -> usize { self.id }
 
diff --git a/src/libstd/sync/mpsc/shared.rs b/src/libstd/sync/mpsc/shared.rs
index af538b75b70..3da73ac0b82 100644
--- a/src/libstd/sync/mpsc/shared.rs
+++ b/src/libstd/sync/mpsc/shared.rs
@@ -1,4 +1,4 @@
-/// Shared channels
+/// Shared channels.
 ///
 /// This is the flavor of channels which are not necessarily optimized for any
 /// particular use case, but are the most general in how they are used. Shared
diff --git a/src/libstd/sync/mutex.rs b/src/libstd/sync/mutex.rs
index 59829db23cb..340dca7ce73 100644
--- a/src/libstd/sync/mutex.rs
+++ b/src/libstd/sync/mutex.rs
@@ -335,7 +335,7 @@ impl<T: ?Sized> Mutex<T> {
     /// Returns a mutable reference to the underlying data.
     ///
     /// Since this call borrows the `Mutex` mutably, no actual locking needs to
-    /// take place---the mutable borrow statically guarantees no locks exist.
+    /// take place -- the mutable borrow statically guarantees no locks exist.
     ///
     /// # Errors
     ///
diff --git a/src/libstd/sync/once.rs b/src/libstd/sync/once.rs
index fcab2ffe144..656389789d7 100644
--- a/src/libstd/sync/once.rs
+++ b/src/libstd/sync/once.rs
@@ -228,7 +228,7 @@ impl Once {
     /// result in an immediate panic. If `f` panics, the `Once` will remain
     /// in a poison state. If `f` does _not_ panic, the `Once` will no
     /// longer be in a poison state and all future calls to `call_once` or
-    /// `call_one_force` will no-op.
+    /// `call_one_force` will be no-ops.
     ///
     /// The closure `f` is yielded a [`OnceState`] structure which can be used
     /// to query the poison status of the `Once`.
@@ -279,7 +279,7 @@ impl Once {
         });
     }
 
-    /// Returns true if some `call_once` call has completed
+    /// Returns `true` if some `call_once` call has completed
     /// successfully. Specifically, `is_completed` will return false in
     /// the following situations:
     ///   * `call_once` was not called at all,
@@ -465,7 +465,7 @@ impl<'a> Drop for Finish<'a> {
 }
 
 impl OnceState {
-    /// Returns whether the associated [`Once`] was poisoned prior to the
+    /// Returns `true` if the associated [`Once`] was poisoned prior to the
     /// invocation of the closure passed to [`call_once_force`].
     ///
     /// [`call_once_force`]: struct.Once.html#method.call_once_force
diff --git a/src/libstd/sync/rwlock.rs b/src/libstd/sync/rwlock.rs
index 7fbe0b8c199..730362e2ac8 100644
--- a/src/libstd/sync/rwlock.rs
+++ b/src/libstd/sync/rwlock.rs
@@ -314,7 +314,7 @@ impl<T: ?Sized> RwLock<T> {
     /// Determines whether the lock is poisoned.
     ///
     /// If another thread is active, the lock can still become poisoned at any
-    /// time.  You should not trust a `false` value for program correctness
+    /// time. You should not trust a `false` value for program correctness
     /// without additional synchronization.
     ///
     /// # Examples
@@ -384,7 +384,7 @@ impl<T: ?Sized> RwLock<T> {
     /// Returns a mutable reference to the underlying data.
     ///
     /// Since this call borrows the `RwLock` mutably, no actual locking needs to
-    /// take place---the mutable borrow statically guarantees no locks exist.
+    /// take place -- the mutable borrow statically guarantees no locks exist.
     ///
     /// # Errors
     ///