Better documentation of Synchronization classes.

Author: jdantonio

lib/concurrent/synchronization/abstract_object.rb

@@ -1,78 +1,62 @@
 module Concurrent
   module Synchronization
 
-    # Safe synchronization under any Ruby implementation.
-    # It provides methods like {#synchronize}, {#ns_wait}, {#ns_signal} and {#ns_broadcast}.
-    # Provides a single layer which can improve its implementation over time without changes needed to
-    # the classes using it. Use {Synchronization::Object} not this abstract class.
-    #
-    # @note this object does not support usage together with
-    #   [`Thread#wakeup`](http://ruby-doc.org/core-2.2.0/Thread.html#method-i-wakeup)
-    #   and [`Thread#raise`](http://ruby-doc.org/core-2.2.0/Thread.html#method-i-raise).
-    #   `Thread#sleep` and `Thread#wakeup` will work as expected but mixing `Synchronization::Object#wait` and
-    #   `Thread#wakeup` will not work on all platforms.
-    #
-    # @see {Event} implementation as an example of this class use
-    #
-    # @example simple
-    #   class AnClass < Synchronization::Object
-    #     def initialize
-    #       super
-    #       synchronize { @value = 'asd' }
-    #     end
-    #
-    #     def value
-    #       synchronize { @value }
-    #     end
-    #   end
-    #
-    # @api private
+    # @!macro synchronization_object
+    # @!visibility private
     class AbstractObject
 
-      # @abstract for helper ivar initialization if needed,
-      #   otherwise it can be left empty. It has to call ns_initialize.
-      def initialize
+      # @!macro [attach] synchronization_object_method_initialize
+      #  
+      #   @abstract for helper ivar initialization if needed,
+      #     otherwise it can be left empty. It has to call ns_initialize.
+      def initialize(*args, &block)
         raise NotImplementedError
       end
 
       protected
 
-      # @yield runs the block synchronized against this object,
-      #   equivalent of java's `synchronize(this) {}`
-      # @note can by made public in descendants if required by `public :synchronize`
+      # @!macro [attach] synchronization_object_method_synchronize
+      #  
+      #   @yield runs the block synchronized against this object,
+      #     equivalent of java's `synchronize(this) {}`
+      #   @note can by made public in descendants if required by `public :synchronize`
       def synchronize
         raise NotImplementedError
       end
 
-      # initialization of the object called inside synchronize block
-      # @note has to be called manually when required in children of this class
-      # @example
-      #   class Child < Concurrent::Synchornization::Object
-      #     def initialize(*args, &block)
-      #       super(&nil)
-      #       synchronize { ns_initialize(*args, &block) }
+      # @!macro [attach] synchronization_object_method_ns_initialize
+      #  
+      #   initialization of the object called inside synchronize block
+      #   @note has to be called manually when required in children of this class
+      #   @example
+      #     class Child < Concurrent::Synchornization::Object
+      #       def initialize(*args, &block)
+      #         super(&nil)
+      #         synchronize { ns_initialize(*args, &block) }
+      #       end
+      #     
+      #       def ns_initialize(*args, &block)
+      #         @args = args          
+      #       end
       #     end
-      #   
-      #     def ns_initialize(*args, &block)
-      #       @args = args          
-      #     end
-      #   end
       def ns_initialize(*args, &block)
       end
 
-      # Wait until condition is met or timeout passes,
-      # protects against spurious wake-ups.
-      # @param [Numeric, nil] timeout in seconds, `nil` means no timeout
-      # @yield condition to be met
-      # @yieldreturn [true, false]
-      # @return [true, false] if condition met
-      # @note only to be used inside synchronized block
-      # @note to provide direct access to this method in a descendant add method
-      #   ```
-      #   def wait_until(timeout = nil, &condition)
-      #     synchronize { ns_wait_until(timeout, &condition) }
-      #   end
-      #   ```
+      # @!macro [attach] synchronization_object_method_ns_wait_until
+      #  
+      #   Wait until condition is met or timeout passes,
+      #   protects against spurious wake-ups.
+      #   @param [Numeric, nil] timeout in seconds, `nil` means no timeout
+      #   @yield condition to be met
+      #   @yieldreturn [true, false]
+      #   @return [true, false] if condition met
+      #   @note only to be used inside synchronized block
+      #   @note to provide direct access to this method in a descendant add method
+      #     ```
+      #     def wait_until(timeout = nil, &condition)
+      #       synchronize { ns_wait_until(timeout, &condition) }
+      #     end
+      #     ```
       def ns_wait_until(timeout = nil, &condition)
         if timeout
           wait_until = Concurrent.monotonic_time + timeout
@@ -90,65 +74,75 @@ def ns_wait_until(timeout = nil, &condition)
         end
       end
 
-      # Wait until another thread calls #signal or #broadcast,
-      # spurious wake-ups can happen.
-      #
-      # @param [Numeric, nil] timeout in seconds, `nil` means no timeout
-      # @return [self]
-      # @note only to be used inside synchronized block
-      # @note to provide direct access to this method in a descendant add method
-      #   ```
-      #   def wait(timeout = nil)
-      #     synchronize { ns_wait(timeout) }
-      #   end
-      #   ```
+      # @!macro [attach] synchronization_object_method_ns_wait
+      #  
+      #   Wait until another thread calls #signal or #broadcast,
+      #   spurious wake-ups can happen.
+      #  
+      #   @param [Numeric, nil] timeout in seconds, `nil` means no timeout
+      #   @return [self]
+      #   @note only to be used inside synchronized block
+      #   @note to provide direct access to this method in a descendant add method
+      #     ```
+      #     def wait(timeout = nil)
+      #       synchronize { ns_wait(timeout) }
+      #     end
+      #     ```
       def ns_wait(timeout = nil)
         raise NotImplementedError
       end
 
-      # Signal one waiting thread.
-      # @return [self]
-      # @note only to be used inside synchronized block
-      # @note to provide direct access to this method in a descendant add method
-      #   ```
-      #   def signal
-      #     synchronize { ns_signal }
-      #   end
-      #   ```
+      # @!macro [attach] synchronization_object_method_ns_signal
+      #    
+      #   Signal one waiting thread.
+      #   @return [self]
+      #   @note only to be used inside synchronized block
+      #   @note to provide direct access to this method in a descendant add method
+      #     ```
+      #     def signal
+      #       synchronize { ns_signal }
+      #     end
+      #     ```
       def ns_signal
         raise NotImplementedError
       end
 
-      # Broadcast to all waiting threads.
-      # @return [self]
-      # @note only to be used inside synchronized block
-      # @note to provide direct access to this method in a descendant add method
-      #   ```
-      #   def broadcast
-      #     synchronize { ns_broadcast }
-      #   end
-      #   ```
+      # @!macro [attach] synchronization_object_method_ns_broadcast
+      #  
+      #   Broadcast to all waiting threads.
+      #   @return [self]
+      #   @note only to be used inside synchronized block
+      #   @note to provide direct access to this method in a descendant add method
+      #     ```
+      #     def broadcast
+      #       synchronize { ns_broadcast }
+      #     end
+      #     ```
       def ns_broadcast
         raise NotImplementedError
       end
 
-      # Allows to construct immutable objects where all fields are visible after initialization, not requiring
-      # further synchronization on access.
-      # @example
-      #   class AClass
-      #     attr_reader :val
-      #     def initialize(val)
-      #       @val = val # final value, after assignment it's not changed (just convention, not enforced)
-      #       ensure_ivar_visibility!
-      #       # now it can be shared as Java's final field
+      # @!macro [attach] synchronization_object_method_ensure_ivar_visibility
+      #  
+      #   Allows to construct immutable objects where all fields are visible after initialization, not requiring
+      #   further synchronization on access.
+      #   @example
+      #     class AClass
+      #       attr_reader :val
+      #       def initialize(val)
+      #         @val = val # final value, after assignment it's not changed (just convention, not enforced)
+      #         ensure_ivar_visibility!
+      #         # now it can be shared as Java's final field
+      #       end
       #     end
-      #   end
       def ensure_ivar_visibility!
         raise NotImplementedError
       end
 
-      # creates methods for reading and writing to a instance variable with volatile (Java semantic) instance variable
-      # return [Array<Symbol>] names of defined method names
+      # @!macro [attach] synchronization_object_method_self_attr_volatile
+      #    
+      #   creates methods for reading and writing to a instance variable with volatile (Java semantic) instance variable
+      #   return [Array<Symbol>] names of defined method names
       def self.attr_volatile(*names)
         names.each do |name|
           ivar = :"@volatile_#{name}"

lib/concurrent/synchronization/abstract_struct.rb

@@ -2,7 +2,7 @@ module Concurrent
   module Synchronization
 
     # @!visibility private
-    # @api private
+    # @!macro internal_implementation_note
     module AbstractStruct
 
       # @!visibility private

lib/concurrent/synchronization/java_object.rb

@@ -6,7 +6,8 @@ module Synchronization
     if Concurrent.on_jruby?
       require 'jruby'
 
-      # @api private
+      # @!visibility private
+      # @!macro internal_implementation_note
       class JavaObject < AbstractObject
 
         def self.attr_volatile(*names)

lib/concurrent/synchronization/monitor_object.rb

@@ -1,7 +1,8 @@
 module Concurrent
   module Synchronization
 
-    # @api private
+    # @!visibility private
+    # @!macro internal_implementation_note
     class MonitorObject < MutexObject
       def initialize
         @__lock__      = ::Monitor.new

lib/concurrent/synchronization/mutex_object.rb

@@ -1,7 +1,8 @@
 module Concurrent
   module Synchronization
 
-    # @api private
+    # @!visibility private
+    # @!macro internal_implementation_note
     class MutexObject < AbstractObject
       def initialize
         @__lock__      = ::Mutex.new

lib/concurrent/synchronization/object.rb

@@ -1,7 +1,8 @@
 module Concurrent
   module Synchronization
 
-    # @api private
+    # @!visibility private
+    # @!macro internal_implementation_note
     Implementation = case
                      when Concurrent.on_jruby?
                        JavaObject
@@ -17,8 +18,61 @@ module Synchronization
                      end
     private_constant :Implementation
 
-    # @see AbstractObject AbstractObject which defines interface of this class.
+    # @!macro [attach] synchronization_object
+    #  
+    #   Safe synchronization under any Ruby implementation.
+    #   It provides methods like {#synchronize}, {#wait}, {#signal} and {#broadcast}.
+    #   Provides a single layer which can improve its implementation over time without changes needed to
+    #   the classes using it. Use {Synchronization::Object} not this abstract class.
+    #  
+    #   @note this object does not support usage together with
+    #     [`Thread#wakeup`](http://ruby-doc.org/core-2.2.0/Thread.html#method-i-wakeup)
+    #     and [`Thread#raise`](http://ruby-doc.org/core-2.2.0/Thread.html#method-i-raise).
+    #     `Thread#sleep` and `Thread#wakeup` will work as expected but mixing `Synchronization::Object#wait` and
+    #     `Thread#wakeup` will not work on all platforms.
+    #  
+    #   @see {Event} implementation as an example of this class use
+    #  
+    #   @example simple
+    #     class AnClass < Synchronization::Object
+    #       def initialize
+    #         super
+    #         synchronize { @value = 'asd' }
+    #       end
+    #  
+    #       def value
+    #         synchronize { @value }
+    #       end
+    #     end
+    #
     class Object < Implementation
+
+      # @!method initialize(*args, &block)
+      #   @!macro synchronization_object_method_initialize
+
+      # @!method synchronize
+      #   @!macro synchronization_object_method_synchronize
+
+      # @!method initialize(*args, &block)
+      #   @!macro synchronization_object_method_ns_initialize
+
+      # @!method wait_until(timeout = nil, &condition)
+      #   @!macro synchronization_object_method_ns_wait_until
+
+      # @!method wait(timeout = nil)
+      #   @!macro synchronization_object_method_ns_wait
+
+      # @!method signal
+      #   @!macro synchronization_object_method_ns_signal
+
+      # @!method broadcast
+      #   @!macro synchronization_object_method_ns_broadcast
+
+      # @!method ensure_ivar_visibility!
+      #   @!macro synchronization_object_method_ensure_ivar_visibility
+
+      # @!method self.attr_volatile(*names)
+      #   @!macro synchronization_object_method_self_attr_volatile
     end
   end
 end

lib/concurrent/synchronization/rbx_object.rb

@@ -3,7 +3,8 @@ module Synchronization
 
     if Concurrent.on_rbx?
 
-      # @api private
+      # @!visibility private
+      # @!macro internal_implementation_note
       class RbxObject < AbstractObject
         def initialize
           @Waiters = []