AS guide: documents some Date calculations (calendar reform details pending)

railties/guides/source/active_support_core_extensions.textile

@@ -2648,11 +2648,58 @@ NOTE: Defined in +active_support/core_ext/proc.rb+.
 
 h3. Extensions to +Date+
 
-...
+h4. Calculations
+
+All the following methods are defined in +active_support/core_ext/date/calculations.rb+.
+
+h5. +Date.current+
+
+Active Support defines +Date.current+ to be today in the current time zone. That's like +Date.today+, except that it honors +Time.zone_default+. It also defines +Date.yesterday+ and +Date.tomorrow+, and the instance predicates +past?+, +today?+, and +future?+, all of them relative to +Date.current+.
+
+h5. Named dates
+
+h6. +last_year+, +next_year+
+
+The methods +last_year+ and +next_year+ return a date with the same day/month in the last or next year:
+
+<ruby>
+d = Date.new(2010, 5, 8) # => Sat, 08 May 2010
+d.last_year              # => Fri, 08 May 2009
+d.next_year              # => Sun, 08 May 2011
+</ruby>
+
+If date is the 29th of February of a leap year, you obtain the 28th:
+
+<ruby>
+d = Date.new(2000, 2, 29) # => Tue, 29 Feb 2000
+d.last_year               # => Sun, 28 Feb 1999
+d.next_year               # => Wed, 28 Feb 2001
+</ruby>
+
+h6. +last_month+, +next_month+
+
+The methods +last_month+ and +next_month+ return the a date with the same day in the last or next month:
+
+<ruby>
+d = Date.new(2010, 5, 8) # => Sat, 08 May 2010
+d.last_month             # => Thu, 08 Apr 2010
+d.next_month             # => Tue, 08 Jun 2010
+</ruby>
+
+If such a day does not exist, the last day of the corresponding month is returned:
+
+<ruby>
+Date.new(2000, 5, 31).last_month # => Sun, 30 Apr 2000
+Date.new(2000, 3, 31).last_month # => Tue, 29 Feb 2000
+Date.new(2000, 5, 31).next_month # => Fri, 30 Jun 2000
+Date.new(2000, 1, 31).next_month # => Tue, 29 Feb 2000
+</ruby>
+
+h4. Conversions
 
 h3. Extensions to +DateTime+
 
-...
+NOTE TO SELF: Since +DateTime+ is a subclass of +Date+, you get inherited methods that return +DateTime+ objects.
 
 h3. Extensions to +Time+