Merge pull request #22119 from philr/time_with_zone_documentation

ActiveSupport::TimeWithZone documentation

1 files changed, 42 insertions, 4 deletions

diff --git a/activesupport/lib/active_support/time_with_zone.rb b/activesupport/lib/active_support/time_with_zone.rb
index 910c1f91a5..79cc748cf5 100644
--- a/activesupport/lib/active_support/time_with_zone.rb
+++ b/activesupport/lib/active_support/time_with_zone.rb
@@ -284,8 +284,8 @@ module ActiveSupport
     # 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
+    #   now = Time.zone.now # => Mon, 03 Nov 2014 00:26:28 EST -05:00
+    #   now - 1000          # => Mon, 03 Nov 2014 00: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
@@ -294,8 +294,8 @@ module ActiveSupport
     # 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
+    #   now - 24.hours      # => Sun, 02 Nov 2014 01:26:28 EDT -04:00
+    #   now - 1.day         # => Sun, 02 Nov 2014 00:26:28 EDT -04:00
     def -(other)
       if other.acts_like?(:time)
         to_time - other.to_time
@@ -307,10 +307,48 @@ module ActiveSupport
       end
     end
 
+    # Subtracts an interval of time from the current object's time and returns
+    # the result as a new TimeWithZone object.
+    #
+    #   Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
+    #   now = Time.zone.now # => Mon, 03 Nov 2014 00:26:28 EST -05:00
+    #   now.ago(1000)       # => Mon, 03 Nov 2014 00:09:48 EST -05:00
+    #
+    # If we're 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, <tt>time.ago(24.hours)</tt> will move back exactly 24 hours,
+    # while <tt>time.ago(1.day)</tt> will move back 23-25 hours, depending on
+    # the day.
+    #
+    #   now.ago(24.hours)   # => Sun, 02 Nov 2014 01:26:28 EDT -04:00
+    #   now.ago(1.day)      # => Sun, 02 Nov 2014 00:26:28 EDT -04:00
     def ago(other)
       since(-other)
     end
 
+    # Uses Date to provide precise Time calculations for years, months, and days
+    # according to the proleptic Gregorian calendar. The result is returned as a
+    # new TimeWithZone object.
+    #
+    # The +options+ parameter takes a hash with any of these keys:
+    # <tt>:years</tt>, <tt>:months</tt>, <tt>:weeks</tt>, <tt>:days</tt>,
+    # <tt>:hours</tt>, <tt>:minutes</tt>, <tt>:seconds</tt>.
+    #
+    # If advancing by a value of variable length (i.e., years, weeks, months,
+    # days), move forward from #time, otherwise move forward from #utc, for
+    # accuracy when moving across DST boundaries.
+    #
+    #   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.advance(seconds: 1) # => Sun, 02 Nov 2014 01:26:29 EDT -04:00
+    #   now.advance(minutes: 1) # => Sun, 02 Nov 2014 01:27:28 EDT -04:00
+    #   now.advance(hours: 1)   # => Sun, 02 Nov 2014 01:26:28 EST -05:00
+    #   now.advance(days: 1)    # => Mon, 03 Nov 2014 01:26:28 EST -05:00
+    #   now.advance(weeks: 1)   # => Sun, 09 Nov 2014 01:26:28 EST -05:00
+    #   now.advance(months: 1)  # => Tue, 02 Dec 2014 01:26:28 EST -05:00
+    #   now.advance(years: 1)   # => Mon, 02 Nov 2015 01:26:28 EST -05:00
     def advance(options)
       # If we're advancing a value of variable length (i.e., years, weeks, months, days), advance from #time,
       # otherwise advance from #utc, for accuracy when moving across DST boundaries