more documentation for class_inheritable_*

activesupport/lib/active_support/core_ext/class/inheritable_attributes.rb

@@ -5,6 +5,10 @@ require 'active_support/core_ext/array/extract_options'
 module ClassInheritableAttributes # :nodoc:
 end
 
+# It is recommend to use <tt>class_attribute</tt> over methods defined in this file. Please
+# refer to documentation for <tt>class_attribute</tt> for more infor. Officially it is not
+# deprected but <tt>class_attribute</tt> is faster.
+#
 # Allows attributes to be shared within an inheritance hierarchy. Each descendant gets a copy of
 # their parents' attributes, instead of just a pointer to the same. This means that the child can add elements
 # to, for example, an array without those additions being shared with either their parent, siblings, or
@@ -12,6 +16,24 @@ end
 #
 # The copies of inheritable parent attributes are added to subclasses when they are created, via the
 # +inherited+ hook.
+#
+#  class Person
+#    class_inheritable_accessor :hair_colors
+#  end
+#
+#  Person.hair_colors = [:brown, :black, :blonde, :red]
+#  Person.hair_colors     #=> [:brown, :black, :blonde, :red]
+#  Person.new.hair_colors #=> [:brown, :black, :blonde, :red]
+#
+# To opt out of the instance writer method, pass :instance_writer => false.
+# To opt out of the instance reader method, pass :instance_reader => false.
+#
+#   class Person
+#     cattr_accessor :hair_colors :instance_writer => false, :instance_reader => false
+#   end
+#
+#   Person.new.hair_colors = [:brown]  # => NoMethodError
+#   Person.new.hair_colors             # => NoMethodError
 class Class # :nodoc:
   def class_inheritable_reader(*syms)
     options = syms.extract_options!