Expand documentation for change() method in Time, Date, and DateTime

3 files changed, 15 insertions, 4 deletions

diff --git a/activesupport/lib/active_support/core_ext/date/calculations.rb b/activesupport/lib/active_support/core_ext/date/calculations.rb
index 7fe4161fb4..2daa3b7fa9 100644
--- a/activesupport/lib/active_support/core_ext/date/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/date/calculations.rb
@@ -106,6 +106,7 @@ class Date
   end
 
   # Returns a new Date where one or more of the elements have been changed according to the +options+ parameter.
+  # The +options+ parameter takes a hash with any of these keys: <tt>:years</tt>, <tt>:month</tt>, <tt>:day</tt>.
   #
   #   Date.new(2007, 5, 12).change(:day => 1)                  # => Date.new(2007, 5, 1)
   #   Date.new(2007, 5, 12).change(:year => 2005, :month => 1) # => Date.new(2005, 1, 12)
diff --git a/activesupport/lib/active_support/core_ext/date_time/calculations.rb b/activesupport/lib/active_support/core_ext/date_time/calculations.rb
index fd78044b5d..5fb19f2e6e 100644
--- a/activesupport/lib/active_support/core_ext/date_time/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/date_time/calculations.rb
@@ -31,8 +31,13 @@ class DateTime
   end
 
   # Returns a new DateTime where one or more of the elements have been changed according to the +options+ parameter. The time options
-  # (hour, minute, sec) reset cascadingly, so if only the hour is passed, then minute and sec is set to 0. If the hour and
-  # minute is passed, then sec is set to 0.
+  # (<tt>:hour</tt>, <tt>:minute</tt>, <tt>:sec</tt>) reset cascadingly, so if only the hour is passed, then minute and sec is set to 0. If the hour and
+  # minute is passed, then sec is set to 0.  The +options+ parameter takes a hash with any of these keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>,
+  # <tt>:hour</tt>, <tt>:min</tt>, <tt>:sec</tt>, <tt>:offset</tt>, <tt>:start</tt>.
+  #
+  #   DateTime.new(2012, 8, 29, 22, 35, 0).change(:day => 1)                  # => DateTime.new(2012, 8, 1, 22, 35, 0)
+  #   DateTime.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :day => 1)   # => DateTime.new(1981, 8, 1, 22, 35, 0)
+  #   DateTime.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :hour => 0)  # => DateTime.new(1981, 8, 29, 0, 0, 0)
   def change(options)
     ::DateTime.civil(
       options.fetch(:year, year),
diff --git a/activesupport/lib/active_support/core_ext/time/calculations.rb b/activesupport/lib/active_support/core_ext/time/calculations.rb
index d0f574f2ba..0eb6e9e61d 100644
--- a/activesupport/lib/active_support/core_ext/time/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/time/calculations.rb
@@ -84,8 +84,13 @@ class Time
   end
 
   # Returns a new Time where one or more of the elements have been changed according to the +options+ parameter. The time options
-  # (hour, min, sec, usec) reset cascadingly, so if only the hour is passed, then minute, sec, and usec is set to 0. If the hour and
-  # minute is passed, then sec and usec is set to 0.
+  # (<tt>:hour</tt>, <tt>:min</tt>, <tt>:sec</tt>, <tt>:usec</tt>) reset cascadingly, so if only the hour is passed, then minute, sec, and usec is set to 0.
+  # If the hour and minute is passed, then sec and usec is set to 0.  The +options+ parameter takes a hash with any of these keys: <tt>:year</tt>,
+  # <tt>:month</tt>, <tt>:day</tt>, <tt>:hour</tt>, <tt>:min</tt>, <tt>:sec</tt>, <tt>:usec</tt>.
+  #
+  #   Time.new(2012, 8, 29, 22, 35, 0).change(:day => 1)                  # => Time.new(2012, 8, 1, 22, 35, 0)
+  #   Time.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :day => 1)   # => Time.new(1981, 8, 1, 22, 35, 0)
+  #   Time.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :hour => 0)  # => Time.new(1981, 8, 29, 0, 0, 0)
   def change(options)
     new_year  = options.fetch(:year, year)
     new_month = options.fetch(:month, month)