Better documentation of private API.

jdantonio · jdantonio · commit 251a32fc72e0 · 2015-06-07T20:16:31.000-04:00
diff --git a/lib/concurrent.rb b/lib/concurrent.rb
@@ -26,6 +26,11 @@
 require 'concurrent/timer_task'
 require 'concurrent/tvar'
 
+# @!macro [new] internal_implementation_note
+#
+#   @note **Private Implementation:** This abstraction is a private, internal
+#     implementation detail. It should never be used directly.
+
 # @!macro [new] monotonic_clock_warning
 #
 #   @note Time calculations one all platforms and languages are sensitive to
diff --git a/lib/concurrent/actor.rb b/lib/concurrent/actor.rb
@@ -11,6 +11,8 @@ module Concurrent
   # TODO more effective executor
 
   # {include:file:doc/actor/main.md}
+  # @api Actor
+  # @!macro edge_warning
   module Actor
 
     require 'concurrent/actor/type_check'
diff --git a/lib/concurrent/agent.rb b/lib/concurrent/agent.rb
@@ -79,6 +79,8 @@ module Concurrent
   #
   # @!attribute [r] timeout
   #   @return [Fixnum] the maximum number of seconds before an update is cancelled
+  #
+  # @!macro edge_warning
   class Agent
     include Concern::Dereferenceable
     include Concern::Observable
diff --git a/lib/concurrent/atomic/atomic_boolean.rb b/lib/concurrent/atomic/atomic_boolean.rb
@@ -23,7 +23,9 @@ module Concurrent
   #
   #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicBoolean.html java.util.concurrent.atomic.AtomicBoolean
   #
-  # @api private
+  # @!visibility private
+  #
+  # @!macro internal_implementation_note
   class MutexAtomicBoolean < Synchronization::Object
 
     # @!macro [attach] atomic_boolean_method_initialize
@@ -107,7 +109,8 @@ def ns_make_value(value)
     end
   end
 
-  # @api private
+  # @!visibility private
+  # @!macro internal_implementation_note
   AtomicBooleanImplementation = case
                                 when Concurrent.on_jruby?
                                   JavaAtomicBoolean
diff --git a/lib/concurrent/atomic/atomic_fixnum.rb b/lib/concurrent/atomic/atomic_fixnum.rb
@@ -23,7 +23,8 @@ module Concurrent
   #
   #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicLong.html java.util.concurrent.atomic.AtomicLong
   #
-  # @api private
+  # @!visibility private
+  # @!macro internal_implementation_note
   class MutexAtomicFixnum < Synchronization::Object
 
     # http://stackoverflow.com/questions/535721/ruby-max-integer
@@ -134,7 +135,8 @@ def range_check!(value)
     end
   end
 
-  # @api private
+  # @!visibility private
+  # @!macro internal_implementation_note
   AtomicFixnumImplementation = case
                                when Concurrent.on_jruby?
                                  JavaAtomicFixnum
diff --git a/lib/concurrent/atomic/count_down_latch.rb b/lib/concurrent/atomic/count_down_latch.rb
@@ -12,7 +12,8 @@ module Concurrent
   #   When the latch counter reaches zero the waiting thread is unblocked and continues
   #   with its work. A `CountDownLatch` can be used only once. Its value cannot be reset.
   #
-  # @api private
+  # @!visibility private
+  # @!macro internal_implementation_note
   class PureCountDownLatch < Synchronization::Object
 
     # @!macro [attach] count_down_latch_method_initialize
@@ -71,7 +72,8 @@ def ns_initialize(count)
   if Concurrent.on_jruby?
 
     # @!macro count_down_latch
-    # @api private
+    # @!visibility private
+    # @!macro internal_implementation_note
     class JavaCountDownLatch
 
       # @!macro count_down_latch_method_initialize
diff --git a/lib/concurrent/atomic/semaphore.rb b/lib/concurrent/atomic/semaphore.rb
@@ -10,6 +10,10 @@ module Concurrent
   #   releasing a blocking acquirer.
   #   However, no actual permit objects are used; the Semaphore just keeps a
   #   count of the number available and acts accordingly.
+  #
+  # @!visibility private
+  #
+  # @!macro internal_implementation_note
   class MutexSemaphore < Synchronization::Object
 
     # @!macro [attach] semaphore_method_initialize
@@ -163,6 +167,8 @@ def try_acquire_timed(permits, timeout)
     end
   end
 
+  # @!visibility private
+  # @!macro internal_implementation_note
   SemaphoreImplementation = case
                             when Concurrent.on_jruby?
                               JavaSemaphore
diff --git a/lib/concurrent/atomic/thread_local_var.rb b/lib/concurrent/atomic/thread_local_var.rb
@@ -32,6 +32,8 @@ module Concurrent
   #     v.value #=> 14
   #
   #   @see https://docs.oracle.com/javase/7/docs/api/java/lang/ThreadLocal.html Java ThreadLocal
+  #
+  # @!visibility private
   class AbstractThreadLocalVar
 
     # @api private
@@ -113,6 +115,8 @@ def set(value)
     end
   end
 
+  # @!visibility private
+  # @!macro internal_implementation_note
   class RubyThreadLocalVar < AbstractThreadLocalVar
 
     protected
@@ -145,6 +149,8 @@ def set(value)
 
   if Concurrent.on_jruby?
 
+    # @!visibility private
+    # @!macro internal_implementation_note
     class JavaThreadLocalVar < AbstractThreadLocalVar
 
       protected
@@ -166,6 +172,8 @@ def set(value)
     end
   end
 
+  # @!visibility private
+  # @!macro internal_implementation_note
   ThreadLocalVarImplementation = case
                                  when Concurrent.on_jruby?
                                    JavaThreadLocalVar
@@ -175,9 +183,6 @@ def set(value)
   private_constant :ThreadLocalVarImplementation
 
   # @!macro thread_local_var
-  #
-  # @see Concurrent::AbstractThreadLocalVar
-  # @see Concurrent::RubyThreadLocalVar
   class ThreadLocalVar < ThreadLocalVarImplementation
 
     # @!method initialize(default = nil)
diff --git a/lib/concurrent/atomic/thread_local_var/weak_key_map.rb b/lib/concurrent/atomic/thread_local_var/weak_key_map.rb
@@ -21,7 +21,7 @@
 
 module Concurrent
 
-  # @api private
+  # @!visibility private
   class AbstractThreadLocalVar
 
     begin
diff --git a/lib/concurrent/atomic_reference/direct_update.rb b/lib/concurrent/atomic_reference/direct_update.rb
@@ -3,7 +3,9 @@
 module Concurrent
 
   # Define update methods that use direct paths
-  # @api private
+  #
+  # @!visibility private
+  # @!macro internal_implementation_note
   module AtomicDirectUpdate
 
     # @!macro [attach] atomic_reference_method_update
diff --git a/lib/concurrent/atomic_reference/jruby.rb b/lib/concurrent/atomic_reference/jruby.rb
@@ -6,7 +6,9 @@
   module Concurrent
 
     # @!macro atomic_reference
-    # @api private
+    #
+    # @!visibility private
+    # @!macro internal_implementation_note
     class JavaAtomicReference
       include Concurrent::AtomicDirectUpdate
     end
diff --git a/lib/concurrent/atomic_reference/mutex_atomic.rb b/lib/concurrent/atomic_reference/mutex_atomic.rb
@@ -5,46 +5,32 @@
 module Concurrent
 
   # @!macro atomic_reference
-  # @api private
+  #
+  # @!visibility private
+  # @!macro internal_implementation_note
   class MutexAtomicReference
     include Concurrent::AtomicDirectUpdate
     include Concurrent::AtomicNumericCompareAndSetWrapper
 
-    # @!macro [attach] atomic_reference_method_initialize
+    # @!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
+    # @!macro atomic_reference_method_get
     def get
       @mutex.synchronize { @value }
     end
     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
+    # @!macro atomic_reference_method_set
     def set(new_value)
       @mutex.synchronize { @value = new_value }
     end
     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
+    # @!macro atomic_reference_method_get_and_set
     def get_and_set(new_value)
       @mutex.synchronize do
         old_value = @value
@@ -54,17 +40,8 @@ def get_and_set(new_value)
     end
     alias_method :swap, :get_and_set
 
-    # @!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:
+    # @!macro atomic_reference_method_compare_and_set
+    def _compare_and_set(old_value, new_value)
       return false unless @mutex.try_lock
       begin
         return false unless @value.equal? old_value
diff --git a/lib/concurrent/atomic_reference/numeric_cas_wrapper.rb b/lib/concurrent/atomic_reference/numeric_cas_wrapper.rb
@@ -1,7 +1,9 @@
 module Concurrent
 
   # Special "compare and set" handling of numeric values.
-  # @api private
+  #
+  # @!visibility private
+  # @!macro internal_implementation_note
   module AtomicNumericCompareAndSetWrapper
 
     # @!macro atomic_reference_method_compare_and_set
diff --git a/lib/concurrent/atomic_reference/rbx.rb b/lib/concurrent/atomic_reference/rbx.rb
@@ -7,7 +7,9 @@ module Concurrent
   #
   # @note Extends `Rubinius::AtomicReference` version adding aliases
   #   and numeric logic.
-  # @api private
+  #
+  # @!visibility private
+  # @!macro internal_implementation_note
   class RbxAtomicReference < Rubinius::AtomicReference
     alias _compare_and_set compare_and_set
     include Concurrent::AtomicDirectUpdate
diff --git a/lib/concurrent/atomic_reference/ruby.rb b/lib/concurrent/atomic_reference/ruby.rb
@@ -6,7 +6,9 @@
   module Concurrent
 
     # @!macro atomic_reference
-    # @api private
+    #
+    # @!visibility private
+    # @!macro internal_implementation_note
     class CAtomicReference
       include Concurrent::AtomicDirectUpdate
       include Concurrent::AtomicNumericCompareAndSetWrapper
diff --git a/lib/concurrent/atomics.rb b/lib/concurrent/atomics.rb
@@ -36,6 +36,41 @@
 #
 #   @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
+#
+#   @!method initialize
+#     @!macro [new] atomic_reference_method_initialize
+#       @param [Object] value The initial value.
+#   
+#   @!method get
+#     @!macro [new] atomic_reference_method_get
+#       Gets the current value.
+#       @return [Object] the current value
+#   
+#   @!method set
+#     @!macro [new] atomic_reference_method_set
+#       Sets to the given value.
+#       @param [Object] new_value the new value
+#       @return [Object] the new value
+#   
+#   @!method get_and_set
+#     @!macro [new] 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
+#   
+#   @!method _compare_and_set
+#     @!macro [new] 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.
+#
+#       @api private
 
 require 'concurrent/atomic/atomic_reference'
 require 'concurrent/atomic/atomic_boolean'
diff --git a/lib/concurrent/channel/blocking_ring_buffer.rb b/lib/concurrent/channel/blocking_ring_buffer.rb
@@ -3,6 +3,8 @@
 module Concurrent
   module Channel
 
+    # @api Channel
+    # @!macro edge_warning
     class BlockingRingBuffer < Synchronization::Object
 
       def initialize(capacity)
diff --git a/lib/concurrent/channel/buffered_channel.rb b/lib/concurrent/channel/buffered_channel.rb
@@ -3,6 +3,8 @@
 module Concurrent
   module Channel
 
+    # @api Channel
+    # @!macro edge_warning
     class BufferedChannel
 
       def initialize(size)
diff --git a/lib/concurrent/channel/channel.rb b/lib/concurrent/channel/channel.rb
@@ -1,6 +1,9 @@
 require 'concurrent/ivar'
 
 module Concurrent
+  
+  # @api Channel
+  # @!macro edge_warning
   module Channel
 
     Probe = IVar
diff --git a/lib/concurrent/channel/ring_buffer.rb b/lib/concurrent/channel/ring_buffer.rb
@@ -2,6 +2,9 @@ module Concurrent
   module Channel
 
     # non-thread safe buffer
+    #
+    # @api Channel
+    # @!macro edge_warning
     class RingBuffer
 
       def initialize(capacity)
diff --git a/lib/concurrent/channel/unbuffered_channel.rb b/lib/concurrent/channel/unbuffered_channel.rb
@@ -3,6 +3,8 @@
 module Concurrent
   module Channel
 
+    # @api Channel
+    # @!macro edge_warning
     class UnbufferedChannel
 
       def initialize
diff --git a/lib/concurrent/channel/waitable_list.rb b/lib/concurrent/channel/waitable_list.rb
@@ -3,6 +3,8 @@
 module Concurrent
   module Channel
 
+    # @api Channel
+    # @!macro edge_warning
     class WaitableList < Synchronization::Object
 
       def initialize
diff --git a/lib/concurrent/collection/priority_queue.rb b/lib/concurrent/collection/priority_queue.rb
diff --git a/lib/concurrent/concern/deprecation.rb b/lib/concurrent/concern/deprecation.rb
diff --git a/lib/concurrent/edge.rb b/lib/concurrent/edge.rb
diff --git a/lib/concurrent/edge/future.rb b/lib/concurrent/edge/future.rb
diff --git a/lib/concurrent/exchanger.rb b/lib/concurrent/exchanger.rb
diff --git a/lib/concurrent/lazy_register.rb b/lib/concurrent/lazy_register.rb
diff --git a/lib/concurrent/utility/at_exit.rb b/lib/concurrent/utility/at_exit.rb
diff --git a/lib/concurrent/utility/engine.rb b/lib/concurrent/utility/engine.rb
diff --git a/lib/concurrent/utility/monotonic_time.rb b/lib/concurrent/utility/monotonic_time.rb
diff --git a/lib/concurrent/utility/native_extension_loader.rb b/lib/concurrent/utility/native_extension_loader.rb
diff --git a/lib/concurrent/utility/processor_counter.rb b/lib/concurrent/utility/processor_counter.rb

Original file line number	Diff line number	Diff line change
`@@ -79,6 +79,8 @@ module Concurrent`
`79`	`79`	`#`
`80`	`80`	`# @!attribute [r] timeout`
`81`	`81`	`# @return [Fixnum] the maximum number of seconds before an update is cancelled`
	`82`	`+ #`
	`83`	`+ # @!macro edge_warning`
`82`	`84`	`class Agent`
`83`	`85`	`include Concern::Dereferenceable`
`84`	`86`	`include Concern::Observable`