Address review comments

1 files changed, 67 insertions, 43 deletions

diff --git a/src/libstd/sync/mod.rs b/src/libstd/sync/mod.rs
index edbed430e38..d69ebc17622 100644
--- a/src/libstd/sync/mod.rs
+++ b/src/libstd/sync/mod.rs
@@ -12,11 +12,11 @@
 //!
 //! ## The need for synchronization
 //!
-//! Conceptually, a Rust program is simply a series of operations which will
-//! be executed on a computer. The timeline of events happening in the program
-//! is consistent with the order of the operations in the code.
+//! Conceptually, a Rust program is a series of operations which will
+//! be executed on a computer. The timeline of events happening in the
+//! program is consistent with the order of the operations in the code.
 //!
-//! Considering the following code, operating on some global static variables:
+//! Consider the following code, operating on some global static variables:
 //!
 //! ```rust
 //! static mut A: u32 = 0;
@@ -35,8 +35,10 @@
 //! }
 //! ```
 //!
-//! It appears _as if_ some variables stored in memory are changed, an addition
-//! is performed, result is stored in `A` and the variable `C` is modified twice.
+//! It appears as if some variables stored in memory are changed, an addition
+//! is performed, result is stored in `A` and the variable `C` is
+//! modified twice.
+//!
 //! When only a single thread is involved, the results are as expected:
 //! the line `7 4 4` gets printed.
 //!
@@ -50,17 +52,19 @@
 //!   in a temporary location until it gets printed, with the global variable
 //!   never getting updated.
 //!
-//! - The final result could be determined just by looking at the code at compile time,
-//!   so [constant folding] might turn the whole block into a simple `println!("7 4 4")`.
+//! - The final result could be determined just by looking at the code
+//!   at compile time, so [constant folding] might turn the whole
+//!   block into a simple `println!("7 4 4")`.
 //!
-//! The compiler is allowed to perform any combination of these optimizations, as long
-//! as the final optimized code, when executed, produces the same results as the one
-//! without optimizations.
+//! The compiler is allowed to perform any combination of these
+//! optimizations, as long as the final optimized code, when executed,
+//! produces the same results as the one without optimizations.
 //!
-//! Due to the [concurrency] involved in modern computers, assumptions about
-//! the program's execution order are often wrong. Access to global variables
-//! can lead to nondeterministic results, **even if** compiler optimizations
-//! are disabled, and it is **still possible** to introduce synchronization bugs.
+//! Due to the [concurrency] involved in modern computers, assumptions
+//! about the program's execution order are often wrong. Access to
+//! global variables can lead to nondeterministic results, **even if**
+//! compiler optimizations are disabled, and it is **still possible**
+//! to introduce synchronization bugs.
 //!
 //! Note that thanks to Rust's safety guarantees, accessing global (static)
 //! variables requires `unsafe` code, assuming we don't use any of the
@@ -74,7 +78,7 @@
 //! Instructions can execute in a different order from the one we define, due to
 //! various reasons:
 //!
-//! - **Compiler** reordering instructions: if the compiler can issue an
+//! - The **compiler** reordering instructions: If the compiler can issue an
 //!   instruction at an earlier point, it will try to do so. For example, it
 //!   might hoist memory loads at the top of a code block, so that the CPU can
 //!   start [prefetching] the values from memory.
@@ -83,20 +87,20 @@
 //!   signal handlers or certain kinds of low-level code.
 //!   Use [compiler fences] to prevent this reordering.
 //!
-//! - **Single processor** executing instructions [out-of-order]: modern CPUs are
-//!   capable of [superscalar] execution, i.e. multiple instructions might be
-//!   executing at the same time, even though the machine code describes a
-//!   sequential process.
+//! - A **single processor** executing instructions [out-of-order]:
+//!   Modern CPUs are capable of [superscalar] execution,
+//!   i.e. multiple instructions might be executing at the same time,
+//!   even though the machine code describes a sequential process.
 //!
 //!   This kind of reordering is handled transparently by the CPU.
 //!
-//! - **Multiprocessor** system, where multiple hardware threads run at the same time.
-//!   In multi-threaded scenarios, you can use two kinds of primitives to deal
-//!   with synchronization:
-//!   - [memory fences] to ensure memory accesses are made visibile to other
-//!     CPUs in the right order.
-//!   - [atomic operations] to ensure simultaneous access to the same memory
-//!     location doesn't lead to undefined behavior.
+//! - A **multiprocessor** system executing multiple hardware threads
+//!   at the same time: In multi-threaded scenarios, you can use two
+//!   kinds of primitives to deal with synchronization:
+//!   - [memory fences] to ensure memory accesses are made visibile to
+//!   other CPUs in the right order.
+//!   - [atomic operations] to ensure simultaneous access to the same
+//!   memory location doesn't lead to undefined behavior.
 //!
 //! [prefetching]: https://en.wikipedia.org/wiki/Cache_prefetching
 //! [compiler fences]: crate::sync::atomic::compiler_fence
@@ -111,29 +115,49 @@
 //! inconvenient to use, which is why the standard library also exposes some
 //! higher-level synchronization objects.
 //!
-//! These abstractions can be built out of lower-level primitives. For efficiency,
-//! the sync objects in the standard library are usually implemented with help
-//! from the operating system's kernel, which is able to reschedule the threads
-//! while they are blocked on acquiring a lock.
+//! These abstractions can be built out of lower-level primitives.
+//! For efficiency, the sync objects in the standard library are usually
+//! implemented with help from the operating system's kernel, which is
+//! able to reschedule the threads while they are blocked on acquiring
+//! a lock.
+//!
+//! The following is an overview of the available synchronization
+//! objects:
+//!
+//! - [`Arc`]: Atomically Reference-Counted pointer, which can be used
+//!   in multithreaded environments to prolong the lifetime of some
+//!   data until all the threads have finished using it.
+//!
+//! - [`Barrier`]: Ensures multiple threads will wait for each other
+//!   to reach a point in the program, before continuing execution all
+//!   together.
+//!
+//! - [`Condvar`]: Condition Variable, providing the ability to block
+//!   a thread while waiting for an event to occur.
 //!
-//! ## Efficiency
+//! - [`mpsc`]: Multi-producer, single-consumer queues, used for
+//!   message-based communication. Can provide a lightweight
+//!   inter-thread synchronisation mechanism, at the cost of some
+//!   extra memory.
 //!
-//! Higher-level synchronization mechanisms are usually heavy-weight.
-//! While most atomic operations can execute instantaneously, acquiring a
-//! [`Mutex`] can involve blocking until another thread releases it.
-//! For [`RwLock`], while any number of readers may acquire it without
-//! blocking, each writer will have exclusive access.
+//! - [`Mutex`]: Mutual Exclusion mechanism, which ensures that at
+//!   most one thread at a time is able to access some data.
 //!
-//! On the other hand, communication over [channels] can provide a fairly
-//! high-level interface without sacrificing performance, at the cost of
-//! somewhat more memory.
+//! - [`Once`]: Used for thread-safe, one-time initialization of a
+//!   global variable.
 //!
-//! The more synchronization exists between CPUs, the smaller the performance
-//! gains from multithreading will be.
+//! - [`RwLock`]: Provides a mutual exclusion mechanism which allows
+//!   multiple readers at the same time, while allowing only one
+//!   writer at a time. In some cases, this can be more efficient than
+//!   a mutex.
 //!
+//! [`Arc`]: crate::sync::Arc
+//! [`Barrier`]: crate::sync::Barrier
+//! [`Condvar`]: crate::sync::Condvar
+//! [`mpsc`]: crate::sync::mpsc
 //! [`Mutex`]: crate::sync::Mutex
+//! [`Once`]: crate::sync::Once
 //! [`RwLock`]: crate::sync::RwLock
-//! [channels]: crate::sync::mpsc
 
 #![stable(feature = "rust1", since = "1.0.0")]