More docs fixes

Rakefile

@@ -337,9 +337,9 @@ namespace :release do
     desc '** print post release steps'
     task :post_steps do
       # TODO: (petr 05-Jun-2021) automate and renew the process
-      # puts 'Manually: create a release on GitHub with relevant changelog part'
-      # puts 'Manually: send email same as release with relevant changelog part'
-      # puts 'Manually: tweet'
+      puts 'Manually: create a release on GitHub with relevant changelog part'
+      puts 'Manually: send email same as release with relevant changelog part'
+      puts 'Manually: tweet'
     end
   end
 end

lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb

@@ -14,58 +14,6 @@ module TruffleRuby
 
 module Concurrent
 
-  # @!macro atomic_reference
-  #
-  #   An object reference that may be updated atomically. All read and write
-  #   operations have java volatile semantic.
-  #
-  #   @!macro thread_safe_variable_comparison
-  #
-  #   @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(value = nil)
-  #     @!macro atomic_reference_method_initialize
-  #       @param [Object] value The initial value.
-  #
-  #   @!method get
-  #     @!macro atomic_reference_method_get
-  #       Gets the current value.
-  #       @return [Object] the current value
-  #
-  #   @!method set(new_value)
-  #     @!macro 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(new_value)
-  #     @!macro 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(old_value, new_value)
-  #     @!macro 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.
-  #
-  #   @!method update
-  #     @!macro atomic_reference_method_update
-  #
-  #   @!method try_update
-  #     @!macro atomic_reference_method_try_update
-  #
-  #   @!method try_update!
-  #     @!macro atomic_reference_method_try_update!
-
   # @!macro internal_implementation_note
   AtomicReferenceImplementation = case
                                   when Concurrent.on_cruby? && Concurrent.c_extensions_loaded?
@@ -98,7 +46,83 @@ class TruffleRubyAtomicReference < TruffleRuby::AtomicReference
                                   end
   private_constant :AtomicReferenceImplementation
 
-  # @!macro atomic_reference
+  # An object reference that may be updated atomically. All read and write
+  # operations have java volatile semantic.
+  #
+  # @!macro thread_safe_variable_comparison
+  #
+  # @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(value = nil)
+  #   @!macro atomic_reference_method_initialize
+  #     @param [Object] value The initial value.
+  #
+  # @!method get
+  #   @!macro atomic_reference_method_get
+  #     Gets the current value.
+  #     @return [Object] the current value
+  #
+  # @!method set(new_value)
+  #   @!macro 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(new_value)
+  #   @!macro 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(old_value, new_value)
+  #   @!macro 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.
+  #
+  # @!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
+  #
+  # @!method try_update
+  #   Pass the current value to the given block, replacing it
+  #   with the block's result. Return nil 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
+  #   @note This method was altered to avoid raising an exception by default.
+  #     Instead, this method now returns `nil` in case of failure. For more info,
+  #     please see: https://github.com/ruby-concurrency/concurrent-ruby/pull/336
+  #   @return [Object] the new value, or nil if update failed
+  #
+  # @!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
+  #   @note This behavior mimics the behavior of the original
+  #     `AtomicReference#try_update` API. The reason this was changed was to
+  #     avoid raising exceptions (which are inherently slow) by default. For more
+  #     info: https://github.com/ruby-concurrency/concurrent-ruby/pull/336
+  #   @return [Object] the new value
+  #   @raise [Concurrent::ConcurrentUpdateError] if the update fails
   class AtomicReference < AtomicReferenceImplementation
 
     # @return [String] Short string representation.

lib/concurrent-ruby/concurrent/atomic_reference/atomic_direct_update.rb

@@ -7,34 +7,11 @@ module Concurrent
   # @!visibility private
   # @!macro internal_implementation_note
   module AtomicDirectUpdate
-
-    # @!macro 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 atomic_reference_method_try_update
-    #
-    #   Pass the current value to the given block, replacing it
-    #   with the block's result. Return nil 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
-    #   @note This method was altered to avoid raising an exception by default.
-    #     Instead, this method now returns `nil` in case of failure. For more info,
-    #     please see: https://github.com/ruby-concurrency/concurrent-ruby/pull/336
-    #   @return [Object] the new value, or nil if update failed
     def try_update
       old_value = get
       new_value = yield old_value
@@ -44,21 +21,6 @@ def try_update
       new_value
     end
 
-    # @!macro 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
-    #   @note This behavior mimics the behavior of the original
-    #     `AtomicReference#try_update` API. The reason this was changed was to
-    #     avoid raising exceptions (which are inherently slow) by default. For more
-    #     info: https://github.com/ruby-concurrency/concurrent-ruby/pull/336
-    #   @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-ruby/concurrent/synchronization.rb

@@ -6,8 +6,7 @@
 require 'concurrent/synchronization/lock'
 
 module Concurrent
-  # {include:file:docs-source/synchronization.md}
-  # {include:file:docs-source/synchronization-notes.md}
+  # @!visibility private
   module Synchronization
   end
 end