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

2 files changed, 37 insertions, 5 deletions

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 dc4e767e9d..55ad384f4f 100644
--- a/activesupport/lib/active_support/core_ext/date_time/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/date_time/calculations.rb
@@ -10,7 +10,11 @@ class DateTime
     end
   end
 
-  # Seconds since midnight: DateTime.now.seconds_since_midnight.
+  # Returns the number of seconds since 00:00:00.
+  #
+  #   DateTime.new(2012, 8, 29,  0,  0,  0).seconds_since_midnight # => 0
+  #   DateTime.new(2012, 8, 29, 12, 34, 56).seconds_since_midnight # => 45296
+  #   DateTime.new(2012, 8, 29, 23, 59, 59).seconds_since_midnight # => 86399
   def seconds_since_midnight
     sec + (min * 60) + (hour * 3600)
   end
diff --git a/activesupport/lib/active_support/time_with_zone.rb b/activesupport/lib/active_support/time_with_zone.rb
index 9703fb6d28..fb10b40b84 100644
--- a/activesupport/lib/active_support/time_with_zone.rb
+++ b/activesupport/lib/active_support/time_with_zone.rb
@@ -252,9 +252,23 @@ module ActiveSupport
       utc.hash
     end
 
+    # Adds an interval of time to the current object's time and return that
+    # value as a new TimeWithZone object.
+    #
+    #   Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
+    #   now = Time.zone.now # => Sun, 02 Nov 2014 01:26:28 EDT -04:00
+    #   now + 1000          # => Sun, 02 Nov 2014 01:43:08 EDT -04:00
+    #
+    # If we're adding a Duration of variable length (i.e., years, months, days),
+    # move forward from #time, otherwise move forward from #utc, for accuracy
+    # when moving across DST boundaries.
+    #
+    # For instance, a time + 24.hours will advance exactly 24 hours, while a
+    # time + 1.day will advance 23-25 hours, depending on the day.
+    #
+    #   now + 24.hours      # => Mon, 03 Nov 2014 00:26:28 EST -05:00
+    #   now + 1.day         # => Mon, 03 Nov 2014 01:26:28 EST -05:00
     def +(other)
-      # If we're adding a Duration of variable length (i.e., years, months, days), move forward from #time,
-      # otherwise move forward from #utc, for accuracy when moving across DST boundaries
       if duration_of_variable_length?(other)
         method_missing(:+, other)
       else
@@ -263,9 +277,23 @@ module ActiveSupport
       end
     end
 
+    # Returns a new TimeWithZone object that represents the difference between
+    # the current object's time and the +other+ time.
+    #
+    #   Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
+    #   now = Time.zone.now # => Sun, 02 Nov 2014 01:26:28 EST -05:00
+    #   now - 1000          # => Sun, 02 Nov 2014 01:09:48 EST -05:00
+    #
+    # If subtracting a Duration of variable length (i.e., years, months, days),
+    # move backward from #time, otherwise move backward from #utc, for accuracy
+    # when moving across DST boundaries.
+    #
+    # For instance, a time - 24.hours will go subtract exactly 24 hours, while a
+    # time - 1.day will subtract 23-25 hours, depending on the day.
+    #
+    #   now - 24.hours      # => Sat, 01 Nov 2014 02:26:28 EDT -04:00
+    #   now - 1.day         # => Sat, 01 Nov 2014 01:26:28 EDT -04:00
     def -(other)
-      # If we're subtracting a Duration of variable length (i.e., years, months, days), move backwards from #time,
-      # otherwise move backwards #utc, for accuracy when moving across DST boundaries
       if other.acts_like?(:time)
         to_time - other.to_time
       elsif duration_of_variable_length?(other)