Add documentation for TimeWithZone #ago and #advance.

1 files changed, 38 insertions, 0 deletions

diff --git a/activesupport/lib/active_support/time_with_zone.rb b/activesupport/lib/active_support/time_with_zone.rb
index 910c1f91a5..fa19961cec 100644
--- a/activesupport/lib/active_support/time_with_zone.rb
+++ b/activesupport/lib/active_support/time_with_zone.rb
@@ -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