Merge branch 'master' of github.com:lifo/docrails

3 files changed, 55 insertions, 17 deletions

diff --git a/activesupport/lib/active_support/core_ext/class/attribute.rb b/activesupport/lib/active_support/core_ext/class/attribute.rb
index 576366e496..bfa57fe1f7 100644
--- a/activesupport/lib/active_support/core_ext/class/attribute.rb
+++ b/activesupport/lib/active_support/core_ext/class/attribute.rb
@@ -2,8 +2,8 @@ require 'active_support/core_ext/kernel/singleton_class'
 require 'active_support/core_ext/module/remove_method'
 
 class Class
-  # Declare a class-level attribute whose value is inheritable and
-  # overwritable by subclasses:
+  # Declare a class-level attribute whose value is inheritable by subclasses.
+  # Subclasses can change their own value and it will not impact parent class.
   #
   #   class Base
   #     class_attribute :setting
@@ -18,12 +18,34 @@ class Class
   #   Subclass.setting            # => false
   #   Base.setting                # => true
   #
+  # In the above case as long as Subclass does not assign a value to setting
+  # by performing <tt>Subclass.setting = _something_ </tt>, <tt>Subclass.setting</tt>
+  # would read value assigned to parent class. Once Subclass assigns a value then
+  # the value assigned by Subclass would be returned.
+  #
   # This matches normal Ruby method inheritance: think of writing an attribute
-  # on a subclass as overriding the reader method.
+  # on a subclass as overriding the reader method. However, you need to be aware
+  # when using +class_attribute+ with mutable structures as +Array+ or +Hash+.
+  # In such cases, you don't want to do changes in places but use setters:
+  #
+  #   Base.setting = []
+  #   Base.setting                #=> []
+  #   Subclass.setting            #=> []
+  #
+  #   # Appending in child changes both parent and child because it is the same object:
+  #   Subclass.setting << :foo
+  #   Base.setting               #=> [:foo]
+  #   Subclass.setting           #=> [:foo]
+  #
+  #   # Use setters to not propagate changes:
+  #   Base.setting = []
+  #   Subclass.setting += [:foo]
+  #   Base.setting               #=> []
+  #   Subclass.setting           #=> [:foo]
   #
   # For convenience, a query method is defined as well:
   #
-  #   Subclass.setting?           # => false
+  #   Subclass.setting?       # => false
   #
   # Instances may overwrite the class value in the same way:
   #
diff --git a/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb b/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb
index feef5d2d57..4e35b1b488 100644
--- a/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb
+++ b/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb
@@ -3,11 +3,27 @@ require 'active_support/core_ext/array/extract_options'
 # Extends the class object with class and instance accessors for class attributes,
 # just like the native attr* accessors for instance attributes.
 #
+# Note that unlike +class_attribute+, if a subclass changes the value then that would
+# also change the value for parent class. Similarly if parent class changes the value
+# then that would change the value of subclasses too.
+#
 #  class Person
 #    cattr_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
   def cattr_reader(*syms)
     options = syms.extract_options!
diff --git a/activesupport/lib/active_support/core_ext/date/calculations.rb b/activesupport/lib/active_support/core_ext/date/calculations.rb
index e6a213625c..c5b54318ce 100644
--- a/activesupport/lib/active_support/core_ext/date/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/date/calculations.rb
@@ -40,23 +40,23 @@ class Date
     end
   end
 
-  # Tells whether the Date object's date lies in the past
+  # Returns true if the Date object's date lies in the past. Otherwise returns false.
   def past?
     self < ::Date.current
   end
 
-  # Tells whether the Date object's date is today
+  # Returns true if the Date object's date is today.
   def today?
     self.to_date == ::Date.current # we need the to_date because of DateTime
   end
 
-  # Tells whether the Date object's date lies in the future
+  # Returns true if the Date object's date lies in the future.
   def future?
     self > ::Date.current
   end
 
   # Converts Date to a Time (or DateTime if necessary) with the time portion set to the beginning of the day (0:00)
-  # and then subtracts the specified number of seconds
+  # and then subtracts the specified number of seconds.
   def ago(seconds)
     to_time_in_current_zone.since(-seconds)
   end
@@ -127,22 +127,22 @@ class Date
     )
   end
 
-  # Returns a new Date/DateTime representing the time a number of specified months ago
+  # Returns a new Date/DateTime representing the time a number of specified months ago.
   def months_ago(months)
     advance(:months => -months)
   end
 
-  # Returns a new Date/DateTime representing the time a number of specified months in the future
+  # Returns a new Date/DateTime representing the time a number of specified months in the future.
   def months_since(months)
     advance(:months => months)
   end
 
-  # Returns a new Date/DateTime representing the time a number of specified years ago
+  # Returns a new Date/DateTime representing the time a number of specified years ago.
   def years_ago(years)
     advance(:years => -years)
   end
 
-  # Returns a new Date/DateTime representing the time a number of specified years in the future
+  # Returns a new Date/DateTime representing the time a number of specified years in the future.
   def years_since(years)
     advance(:years => years)
   end
@@ -152,22 +152,22 @@ class Date
     years_ago(1)
   end unless method_defined?(:prev_year)
 
-  # Short-hand for years_since(1)
+  # Shorthand for years_since(1)
   def next_year
     years_since(1)
   end unless method_defined?(:next_year)
   
-  # Short-hand for months_ago(1)
+  # Shorthand for months_ago(1)
   def prev_month
     months_ago(1)
   end unless method_defined?(:prev_month)
 
-  # Short-hand for months_since(1)
+  # Shorthand for months_since(1)
   def next_month
     months_since(1)
   end unless method_defined?(:next_month)
 
-  # Returns a new Date/DateTime representing the "start" of this week (i.e, Monday; DateTime objects will have time set to 0:00)
+  # Returns a new Date/DateTime representing the "start" of this week (i.e, Monday; DateTime objects will have time set to 0:00).
   def beginning_of_week
     days_to_monday = self.wday!=0 ? self.wday-1 : 6
     result = self - days_to_monday
@@ -176,7 +176,7 @@ class Date
   alias :monday :beginning_of_week
   alias :at_beginning_of_week :beginning_of_week
 
-  # Returns a new Date/DateTime representing the end of this week (Sunday, DateTime objects will have time set to 23:59:59)
+  # Returns a new Date/DateTime representing the end of this week (Sunday, DateTime objects will have time set to 23:59:59).
   def end_of_week
     days_to_sunday = self.wday!=0 ? 7-self.wday : 0
     result = self + days_to_sunday.days