Updated README and yardoc.

Author: jdantonio

README.md

@@ -62,61 +62,59 @@ This library contains a variety of concurrency abstractions at high and low leve
 #### General-purpose Concurrency Abstractions
 
 * [Async](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Async.html): A mixin module that provides simple asynchronous behavior to any standard class/object or object.
-* [Atom](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Atom.html): A way to manage shared, synchronous, independent state.
 * [Future](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Future.html): An asynchronous operation that produces a value.
   * [Dataflow](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#dataflow-class_method): Built on Futures, Dataflow allows you to create a task that will be scheduled when all of its data dependencies are available.
 * [Promise](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promise.html): Similar to Futures, with more features.
 * [ScheduledTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ScheduledTask.html): Like a Future scheduled for a specific future time.
 * [TimerTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TimerTask.html): A Thread that periodically wakes up to perform work at regular intervals.
 
-#### Thread-safe Collection Classes
+#### Thread-safe Value Objects, Structures, and Collections
 
-These classes were originally part of the (deprecated) `thread_safe` gem.
+Collection classes that were originally part of the (deprecated) `thread_safe` gem:
 
 * [Array](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Array.html) A thread-safe subclass of Ruby's standard [Array](http://ruby-doc.org/core-2.2.0/Array.html).
 * [Hash](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Hash.html) A thread-safe subclass of Ruby's standard [Hash](http://ruby-doc.org/core-2.2.0/Hash.html).
 * [Map](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Map.html) A hash-like object that should have much better performance characteristics, especially under high concurrency, than `Concurrent::Hash`.
+* [Tuple](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Tuple.html) A fixed size array with volatile (synchronized, thread safe) getters/setters.
 
-#### Thread-safe Value Objects
+Value objects inspired by other languages:
 
+* [Atom](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Atom.html): A way to manage shared, synchronous, independent state.
 * [Maybe](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Maybe.html) A thread-safe, immutable object representing an optional value, based on
   [Haskell Data.Maybe](https://hackage.haskell.org/package/base-4.2.0.1/docs/Data-Maybe.html).
 * [Delay](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Delay.html) Lazy evaluation of a block yielding an immutable result. Based on Clojure's
    [delay](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Delay.html).
 
-#### Thread-safe Structures
-
-Derived from Ruby's [Struct](http://ruby-doc.org/core-2.2.0/Struct.html):
+Structure classes derived from Ruby's [Struct](http://ruby-doc.org/core-2.2.0/Struct.html):
 
 * [ImmutableStruct](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ImmutableStruct.html) Immutable struct where values are set at construction and cannot be changed later.
 * [MutableStruct](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MutableStruct.html) Synchronized, mutable struct where values can be safely changed at any time.
 * [SettableStruct](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/SettableStruct.html) Synchronized, write-once struct where values can be set at most once, either at construction or any time thereafter.
-* [Tuple](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Tuple.html) A fixed size array with volatile (synchronized, thread safe) getters/setters.
+
+Thread-safe variables:
+
+* [AtomicBoolean](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/AtomicBoolean.html) A boolean value that can be updated atomically.
+* [AtomicFixnum](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/AtomicFixnum.html) A numeric value that can be updated atomically.
+* [AtomicReference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MutexAtomic.html) An object reference that may be updated atomically.
+* [ThreadLocalVar](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ThreadLocalVar.html) A variable where the value is different for each thread.
+* [Volatile](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Volatile.html)
+  Provides `volatile` (in the JVM's sense) attribute accessors implemented atop of `Concurrent::AtomicReference`.
 
 #### Java-inspired ThreadPools and Other Executors
 
 * See the [thread pool](http://ruby-concurrency.github.io/concurrent-ruby/file.thread_pools.html) overview, which also contains a list of other Executors available.
 
 #### Thread Synchronization Classes and Algorithms
 
-* [CountdownLatch](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CountDownLatch.html)
-* [CyclicBarrier](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CyclicBarrier.html)
-* [Event](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Event.html)
-* [Semaphore](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Semaphore.html)
-
-#### Thread-safe Variables
-
-* [AtomicBoolean](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/AtomicBoolean.html)
-* [AtomicFixnum](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/AtomicFixnum.html)
-* [AtomicReference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MutexAtomic.html)
-* [I-Structures](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/IVar.html) (IVar)
-* [M-Structures](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MVar.html) (MVar)
-* [Thread-local variables](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ThreadLocalVar.html)
-* [Software transactional memory](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TVar.html) (TVar)
-* [ReadWriteLock](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ReadWriteLock.html)
-* [ReentrantReadWriteLock](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ReentrantReadWriteLock.html)
-* [Volatile](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Volatile.html)
-  Provides `volatile` (in the JVM's sense) attribute accessors implemented atop of `Concurrent::AtomicReference`.
+* [CountdownLatch](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CountDownLatch.html) A synchronization object that allows one thread to wait on multiple other threads.
+* [CyclicBarrier](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CyclicBarrier.html) A synchronization aid that allows a set of threads to all wait for each other to reach a common barrier point.
+* [Event](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Event.html) Old school kernel-style event.
+* [I-Structure](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/IVar.html) (IVar) Similar to a "future" but can be manually assigned once, after which it becomes immutable.
+* [M-Structure](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MVar.html) (MVar) A synchronized single element container.
+* [ReadWriteLock](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ReadWriteLock.html) A lock that supports multiple readers but only one writer.
+* [ReentrantReadWriteLock](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ReentrantReadWriteLock.html) A read/write lock with reentrant and upgrade features.
+* [Semaphore](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Semaphore.html) A counting-based locking mechanism that uses permits.
+* [Software transactional memory](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TVar.html) (TVar) A transactional variable - a single-element container that is used as part of a transaction.
 
 ### Edge Features
 
@@ -138,8 +136,8 @@ be obeyed though. Features developed in `concurrent-ruby-edge` are expected to m
   Communicating Sequential Processes (CSP).
 * [Exchanger](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Exchanger.html)
 * [LazyRegister](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LazyRegister.html)
-* [Atomic Markable Reference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/AtomicMarkableReference.html)
-* [LockFreeLinked Set](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/LockFreeLinkedSet.html)
+* [AtomicMarkableReference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/AtomicMarkableReference.html)
+* [LockFreeLinkedSet](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/LockFreeLinkedSet.html)
 * [LockFreeStack](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/LockFreeStack.html)
 
 #### Statuses:

lib/concurrent/atomic/cyclic_barrier.rb

@@ -2,6 +2,8 @@
 
 module Concurrent
 
+  # A synchronization aid that allows a set of threads to all wait for each
+  # other to reach a common barrier point.
   class CyclicBarrier < Synchronization::Object
 
     # @!visibility private

lib/concurrent/atomics.rb

@@ -2,38 +2,6 @@
 #
 #   An object reference that may be updated atomically.
 #
-#       Testing with ruby 2.1.2
-#       
-#       *** Sequential updates ***
-#                                 user     system      total        real
-#       no lock               0.000000   0.000000   0.000000 (  0.005502)
-#       mutex                 0.030000   0.000000   0.030000 (  0.025158)
-#       MutexAtomicReference  0.100000   0.000000   0.100000 (  0.103096)
-#       CAtomicReference      0.040000   0.000000   0.040000 (  0.034012)
-#       
-#       *** Parallel updates ***
-#                                 user     system      total        real
-#       no lock               0.010000   0.000000   0.010000 (  0.009387)
-#       mutex                 0.030000   0.010000   0.040000 (  0.032545)
-#       MutexAtomicReference  0.830000   2.280000   3.110000 (  2.146622)
-#       CAtomicReference      0.040000   0.000000   0.040000 (  0.038332)
-#
-#       Testing with jruby 1.9.3
-#       
-#       *** Sequential updates ***
-#                                 user     system      total        real
-#       no lock               0.170000   0.000000   0.170000 (  0.051000)
-#       mutex                 0.370000   0.010000   0.380000 (  0.121000)
-#       MutexAtomicReference  1.530000   0.020000   1.550000 (  0.471000)
-#       JavaAtomicReference   0.370000   0.010000   0.380000 (  0.112000)
-#       
-#       *** Parallel updates ***
-#                                 user     system      total        real
-#       no lock               0.390000   0.000000   0.390000 (  0.105000)
-#       mutex                 0.480000   0.040000   0.520000 (  0.145000)
-#       MutexAtomicReference  1.600000   0.180000   1.780000 (  0.511000)
-#       JavaAtomicReference   0.460000   0.010000   0.470000 (  0.131000)
-#
 #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/AtomicReference.html
 #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/package-summary.html
 #