Refactor Date/Time next_occurring and prev_occurring

These methods were originally added in https://github.com/rails/rails/pull/26600

This includes a couple of refactors to make these methods behave more similarly to other Date/Time extensions added by Active Support:

1. Use `advance` instead of `since` and `ago` to time-travel — this is particularly important to keep the returned instance’s class matching `self`.  Before this change:

    today = Date.today                     # => Tue, 28 Nov 2017
    today.class                            # => Date
    today.next_occurring(:wednesday)       # => Wed, 29 Nov 2017 00:00:00 UTC +00:00
    today.next_occurring(:wednesday).class # => ActiveSupport::TimeWithZone

  After this change, a Date (or Time, or DateTime) instance is properly returned (just like is shown in the new docs).  This is generally how everything else in DateAndTime::Calculations works.

2. Move the tests from the DateTime tests to the DateAndTimeBehavior tests.  The latter location is mixed in to the core_ext tests for _all_ of Date, Time, and DateTime to test the behavior across all of the classes.  The previous location is for testing core_ext functionality added specifically just to DateTime.

3. Better docs!

1 files changed, 12 insertions, 4 deletions

diff --git a/activesupport/lib/active_support/core_ext/date_and_time/calculations.rb b/activesupport/lib/active_support/core_ext/date_and_time/calculations.rb
index 061b79e098..f6cb1a384c 100644
--- a/activesupport/lib/active_support/core_ext/date_and_time/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/date_and_time/calculations.rb
@@ -330,20 +330,28 @@ module DateAndTime
       beginning_of_year..end_of_year
     end
 
-    # Returns specific next occurring day of week
+    # Returns a new date/time representing the next occurrence of the specified day of week.
+    #
+    #   today = Date.today               # => Thu, 14 Dec 2017
+    #   today.next_occurring(:monday)    # => Mon, 18 Dec 2017
+    #   today.next_occurring(:thursday)  # => Thu, 21 Dec 2017
     def next_occurring(day_of_week)
       current_day_number = wday != 0 ? wday - 1 : 6
       from_now = DAYS_INTO_WEEK.fetch(day_of_week) - current_day_number
       from_now += 7 unless from_now > 0
-      since(from_now.days)
+      advance(days: from_now)
     end
 
-    # Returns specific previous occurring day of week
+    # Returns a new date/time representing the previous occurrence of the specified day of week.
+    #
+    #   today = Date.today               # => Thu, 14 Dec 2017
+    #   today.prev_occurring(:monday)    # => Mon, 11 Dec 2017
+    #   today.prev_occurring(:thursday)  # => Thu, 07 Dec 2017
     def prev_occurring(day_of_week)
       current_day_number = wday != 0 ? wday - 1 : 6
       ago = current_day_number - DAYS_INTO_WEEK.fetch(day_of_week)
       ago += 7 unless ago > 0
-      ago(ago.days)
+      advance(days: -ago)
     end
 
     private