Update documentation

Author: pitr-ch

doc/synchronization.md

@@ -1,5 +1,9 @@
 > Quotations are used for notes.
 
+> This is an outdated version of
+> [this document](https://docs.google.com/document/d/1pVzU8w_QF44YzUCCab990Q_WZOdhpKolCIHaiXG-sPw/edit?usp=sharing) 
+> maintained on Google documents.
+
 > This document is work-in-progress.
 > Intentions of this effort and document are: to summarize the behavior
 > of Ruby in concurrent and parallel environment, initiate discussion,
@@ -145,7 +149,7 @@ in parallel environment but it may loose updates, or raise Exceptions. (If
 in a single thread.)
 
 > `concurrent-ruby` contains synchronized versions of `Array` and `Hash` and
-> other thread-safe data structure. 
+> other thread-safe data structure.
 
 > TODO: This section needs more work: e.g. Thread.raise and similar is an open
 > issue, better not to be used.

lib/concurrent/synchronization.rb

@@ -20,6 +20,7 @@
 
 module Concurrent
   # {include:file:doc/synchronization.md}
+  # {include:file:doc/synchronization-notes.md}
   module Synchronization
   end
 end

lib/concurrent/synchronization/object.rb

@@ -22,6 +22,13 @@ module Synchronization
     # - volatile instance variables see {Object.attr_volatile_with_cas}
     class Object < ObjectImplementation
 
+      # @!method self.attr_volatile(*names)
+      #   Creates methods for reading and writing (as `attr_accessor` does) to a instance variable with
+      #   volatile (Java) semantic. The instance variable should be accessed oly through generated methods.
+      #
+      #   @param [Array<Symbol>] names of the instance variables to be volatile
+      #   @return [Array<Symbol>] names of defined method names
+
       # Has to be called by children.
       def initialize
         super
@@ -122,13 +129,6 @@ def self.volatile_cas_fields(inherited = true)
             @volatile_cas_fields
       end
 
-      # @!method self.attr_volatile(*names)
-      #   Creates methods for reading and writing (as `attr_accessor` does) to a instance variable with
-      #   volatile (Java) semantic. The instance variable should be accessed oly through generated methods.
-      #
-      #   @param [Array<Symbol>] names of the instance variables to be volatile
-      #   @return [Array<Symbol>] names of defined method names
-
       private
 
       def self.define_initialize_volatile_with_cas
@@ -137,7 +137,7 @@ def self.define_initialize_volatile_with_cas
           def initialize_volatile_with_cas
             super
             #{assignments}
-        end
+          end
         RUBY
       end