Better Atomic documentation.

Author: jdantonio

lib/concurrent/atomic.rb

@@ -16,30 +16,50 @@
 
 if defined? Concurrent::JavaAtomic
 
+  # @!macro [attach] atomic_reference
+  #
+  #   An object reference that may be updated atomically.
+  #
+  #   @since 0.7.0.rc0
+  #   @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
   class Concurrent::Atomic < Concurrent::JavaAtomic
   end
 
 elsif defined? Concurrent::CAtomic
 
+  # @!macro [attach] concurrent_update_error
+  #
+  # This exception may be thrown by methods that have detected concurrent
+  # modification of an object when such modification is not permissible.
   class Concurrent::Atomic < Concurrent::CAtomic
   end
 
 elsif defined? Concurrent::RbxAtomic
 
+  # @!macro atomic_reference
   class Concurrent::Atomic < Concurrent::RbxAtomic
   end
 
 else
 
+  # @!macro atomic_reference
   class Concurrent::Atomic < Concurrent::MutexAtomic
   end
 end
 
+# @!macro atomic_reference
 class Atomic < Concurrent::Atomic
 
+  # @!macro concurrent_update_error
   ConcurrentUpdateError = Class.new(Concurrent::ConcurrentUpdateError)
 
-  def initialize(*args)
+  # @!macro [attach] atomic_reference_method_initialize
+  #
+  # Creates a new Atomic reference with null initial value.
+  #
+  # @param [Object] value the initial value
+  def initialize(value)
     warn "[DEPRECATED] Please use Concurrent::Atomic instead."
     super
   end

lib/concurrent/atomic_reference/concurrent_update_error.rb

@@ -1,5 +1,6 @@
 module Concurrent
 
+  # @!macro atomic_reference
   class ConcurrentUpdateError < ThreadError
     # frozen pre-allocated backtrace to speed ConcurrentUpdateError
     CONC_UP_ERR_BACKTRACE = ['backtrace elided; set verbose to enable'].freeze

lib/concurrent/atomic_reference/delegated_update.rb

@@ -4,14 +4,36 @@ module Concurrent
 
   # Define update methods that use direct paths
   module AtomicDirectUpdate
+
+    # @!macro [attach] atomic_reference_method_update
+    #
     # Pass the current value to the given block, replacing it
     # with the block's result. May retry if the value changes
     # during the block's execution.
+    # 
+    # @yield [Object] Calculate a new value for the atomic reference using
+    #   given (old) value
+    # @yieldparam [Object] old_value the starting value of the atomic reference
+    #
+    # @return [Object] the new value
     def update
       true until compare_and_set(old_value = get, new_value = yield(old_value))
       new_value
     end
 
+    # @!macro [attach] atomic_reference_method_try_update
+    #
+    # Pass the current value to the given block, replacing it
+    # with the block's result. Raise an exception if the update
+    # fails.
+    # 
+    # @yield [Object] Calculate a new value for the atomic reference using
+    #   given (old) value
+    # @yieldparam [Object] old_value the starting value of the atomic reference
+    #
+    # @return [Object] the new value
+    #
+    # @raise [Concurrent::ConcurrentUpdateError] if the update fails
     def try_update
       old_value = get
       new_value = yield old_value

lib/concurrent/atomic_reference/direct_update.rb

@@ -2,6 +2,8 @@
 require 'concurrent/atomic_reference/direct_update'
 
 module Concurrent
+
+  # @!macro atomic_reference
   class JavaAtomic
     include Concurrent::AtomicDirectUpdate
   end

lib/concurrent/atomic_reference/jruby.rb

@@ -4,36 +4,66 @@
 
 module Concurrent
 
-  # Portable/generic (but not very memory or scheduling-efficient) fallback
-  class MutexAtomic #:nodoc: all
+  # @!macro atomic_reference
+  class MutexAtomic
     include Concurrent::AtomicDirectUpdate
     include Concurrent::AtomicNumericCompareAndSetWrapper
 
+    # @!macro atomic_reference_method_initialize
     def initialize(value = nil)
       @mutex = Mutex.new
       @value = value
     end
 
+    # @!macro [attach] atomic_reference_method_get
+    #
+    # Gets the current value.
+    #
+    # @return [Object] the current value
     def get
       @mutex.synchronize { @value }
     end
-    alias value get
+    alias_method :value, :get
 
+    # @!macro [attach] atomic_reference_method_set
+    #
+    # Sets to the given value.
+    #
+    # @param [Object] new_value the new value
+    #
+    # @return [Object] the new value
     def set(new_value)
       @mutex.synchronize { @value = new_value }
     end
-    alias value= set
+    alias_method :value=, :set
 
+    # @!macro [attach] atomic_reference_method_get_and_set
+    #
+    # Atomically sets to the given value and returns the old value.
+    #
+    # @param [Object] new_value the new value
+    #
+    # @return [Object] the old value
     def get_and_set(new_value)
       @mutex.synchronize do
         old_value = @value
         @value = new_value
         old_value
       end
     end
-    alias swap get_and_set
+    alias_method :swap, :get_and_set
 
-    def _compare_and_set(old_value, new_value)
+    # @!macro [attach] atomic_reference_method_compare_and_set
+    #
+    # Atomically sets the value to the given updated value if
+    # the current value == the expected value.
+    #
+    # @param [Object] old_value the expected value
+    # @param [Object] new_value the new value
+    #
+    # @return [Boolean] `true` if successful. A `false` return indicates
+    # that the actual value was not equal to the expected value.
+    def _compare_and_set(old_value, new_value) #:nodoc:
       return false unless @mutex.try_lock
       begin
         return false unless @value.equal? old_value

lib/concurrent/atomic_reference/mutex_atomic.rb

@@ -1,8 +1,9 @@
 module Concurrent
 
+  # Special "compare and set" handling of numeric values.
   module AtomicNumericCompareAndSetWrapper
-    #alias _compare_and_set compare_and_set
 
+    # @!macro atomic_reference_method_compare_and_set
     def compare_and_set(expected, new)
       if expected.kind_of? Numeric
         while true
@@ -19,6 +20,6 @@ def compare_and_set(expected, new)
         _compare_and_set(expected, new)
       end
     end
-    alias compare_and_swap compare_and_set
+    alias_method :compare_and_swap, :compare_and_set
   end
 end

lib/concurrent/atomic_reference/numeric_cas_wrapper.rb

@@ -3,14 +3,17 @@
 
 module Concurrent
 
-  # extend Rubinius's version adding aliases and numeric logic
+  # @!macro atomic_reference
+  #
+  # @note Extends `Rubinius::AtomicReference` version adding aliases
+  #   and numeric logic.
   class RbxAtomic < Rubinius::AtomicReference
     alias _compare_and_set compare_and_set
     include Concurrent::AtomicDirectUpdate
     include Concurrent::AtomicNumericCompareAndSetWrapper
 
-    alias value get
-    alias value= set
-    alias swap get_and_set
+    alias_method :value, :get
+    alias_method :value=, :set
+    alias_method :swap, :get_and_set
   end
 end

lib/concurrent/atomic_reference/rbx.rb

@@ -9,6 +9,8 @@
 require 'concurrent/atomic_reference/numeric_cas_wrapper'
 
 module Concurrent
+
+  # @!macro atomic_reference
   class CAtomic
     include Concurrent::AtomicDirectUpdate
     include Concurrent::AtomicNumericCompareAndSetWrapper