Merge pull request #10351 from JonRowe/update_as_date_next_week_to_document_intent

Propose better documentation for ActiveSupports `next_week` functionaility

2 files changed, 10 insertions, 5 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 5b89ace66b..0d14cba7cc 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
@@ -109,11 +109,11 @@ module DateAndTime
     alias :at_beginning_of_year :beginning_of_year
 
     # Returns a new date/time representing the given day in the next week.
-    # Week is assumed to start on +start_day+, default is
-    # +Date.beginning_of_week+ or +config.beginning_of_week+ when set.
-    # DateTime objects have their time set to 0:00.
-    def next_week(start_day = Date.beginning_of_week)
-      first_hour{ weeks_since(1).beginning_of_week.days_since(days_span(start_day)) }
+    # The +given_day_in_next_week+ defaults to the beginning of the week
+    # which is determined by +Date.beginning_of_week+ or +config.beginning_of_week+
+    # when set. +DateTime+ objects have their time set to 0:00.
+    def next_week(given_day_in_next_week = Date.beginning_of_week)
+      first_hour{ weeks_since(1).beginning_of_week.days_since(days_span(given_day_in_next_week)) }
     end
 
     # Short-hand for months_since(1).
diff --git a/activesupport/test/core_ext/date_and_time_behavior.rb b/activesupport/test/core_ext/date_and_time_behavior.rb
index 9927856aa2..b4ef5a0597 100644
--- a/activesupport/test/core_ext/date_and_time_behavior.rb
+++ b/activesupport/test/core_ext/date_and_time_behavior.rb
@@ -95,6 +95,11 @@ module DateAndTimeBehavior
   end
 
   def test_next_week
+    #   M   |   T  | W | T | F | S | S #   M   | T |   W   | T |  F  | S | S #
+    #       | 22/2 |   |   |   |   |   # 28/2  |   |       |   |     |   |   # monday in next week `next_week`
+    #       | 22/2 |   |   |   |   |   #       |   |       |   | 4/3 |   |   # friday in next week `next_week(:friday)`
+    # 23/10 |      |   |   |   |   |   # 30/10 |   |       |   |     |   |   # monday in next week `next_week`
+    # 23/10 |      |   |   |   |   |   #       |   |  1/11 |   |     |   |   # wednesday in next week `next_week(:wednesday)`
     assert_equal date_time_init(2005,2,28,0,0,0),  date_time_init(2005,2,22,15,15,10).next_week
     assert_equal date_time_init(2005,3,4,0,0,0),   date_time_init(2005,2,22,15,15,10).next_week(:friday)
     assert_equal date_time_init(2006,10,30,0,0,0), date_time_init(2006,10,23,0,0,0).next_week