Merge pull request #30972 from jcmfernandes/update-core_ext-time-documentation

Make clear that Time core extensions are split between Numeric and Integer

3 files changed, 39 insertions, 11 deletions

diff --git a/activesupport/lib/active_support/core_ext/integer/time.rb b/activesupport/lib/active_support/core_ext/integer/time.rb
index 74c73ab064..66160b3dd7 100644
--- a/activesupport/lib/active_support/core_ext/integer/time.rb
+++ b/activesupport/lib/active_support/core_ext/integer/time.rb
@@ -19,6 +19,8 @@ class Integer
   #
   #   # equivalent to Time.now.advance(months: 4, years: 5)
   #   (4.months + 5.years).from_now
+  #
+  # For other durations, check the extensions to Numeric.
   def months
     ActiveSupport::Duration.months(self)
   end
diff --git a/activesupport/lib/active_support/core_ext/numeric/time.rb b/activesupport/lib/active_support/core_ext/numeric/time.rb
index d62b57fe27..dee9141356 100644
--- a/activesupport/lib/active_support/core_ext/numeric/time.rb
+++ b/activesupport/lib/active_support/core_ext/numeric/time.rb
@@ -7,19 +7,21 @@ require "active_support/core_ext/date/calculations"
 require "active_support/core_ext/date/acts_like"
 
 class Numeric
-  # Enables the use of time calculations and declarations, like 45.minutes + 2.hours + 4.years.
+  # Enables the use of time calculations and declarations, like 45.minutes + 2.hours + 4.weeks.
   #
   # These methods use Time#advance for precise date calculations when using from_now, ago, etc.
   # as well as adding or subtracting their results from a Time object. For example:
   #
-  #   # equivalent to Time.current.advance(months: 1)
+  #   # equivalent to Time.current.advance(days: 1)
   #   1.month.from_now
   #
-  #   # equivalent to Time.current.advance(years: 2)
-  #   2.years.from_now
+  #   # equivalent to Time.current.advance(weeks: 2)
+  #   2.weeks.from_now
   #
-  #   # equivalent to Time.current.advance(months: 4, years: 5)
-  #   (4.months + 5.years).from_now
+  #   # equivalent to Time.current.advance(days: 4, weeks: 5)
+  #   (4.days + 5.weeks).from_now
+  #
+  # For other durations, check the extensions to Integer.
   def seconds
     ActiveSupport::Duration.seconds(self)
   end
diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md
index 067a7b7cb6..54d3dec1c2 100644
--- a/guides/source/active_support_core_extensions.md
+++ b/guides/source/active_support_core_extensions.md
@@ -1796,7 +1796,7 @@ NOTE: Defined in `active_support/core_ext/numeric/bytes.rb`.
 
 ### Time
 
-Enables the use of time calculations and declarations, like `45.minutes + 2.hours + 4.years`.
+Enables the use of time calculations and declarations, like `45.minutes + 2.hours + 4.weeks`.
 
 These methods use Time#advance for precise date calculations when using from_now, ago, etc.
 as well as adding or subtracting their results from a Time object. For example:
@@ -1805,13 +1805,15 @@ as well as adding or subtracting their results from a Time object. For example:
 # equivalent to Time.current.advance(months: 1)
 1.month.from_now
 
-# equivalent to Time.current.advance(years: 2)
-2.years.from_now
+# equivalent to Time.current.advance(weeks: 2)
+2.weeks.from_now
 
-# equivalent to Time.current.advance(months: 4, years: 5)
-(4.months + 5.years).from_now
+# equivalent to Time.current.advance(months: 4, weeks: 5)
+(4.months + 5.weeks).from_now
 ```
 
+WARNING. For other durations please refer to the time extensions to `Integer`.
+
 NOTE: Defined in `active_support/core_ext/numeric/time.rb`.
 
 ### Formatting
@@ -1947,6 +1949,28 @@ The method `ordinalize` returns the ordinal string corresponding to the receiver
 
 NOTE: Defined in `active_support/core_ext/integer/inflections.rb`.
 
+### Time
+
+Enables the use of time calculations and declarations, like `4.months + 5.years`.
+
+These methods use Time#advance for precise date calculations when using from_now, ago, etc.
+as well as adding or subtracting their results from a Time object. For example:
+
+```ruby
+# equivalent to Time.current.advance(months: 1)
+1.month.from_now
+
+# equivalent to Time.current.advance(years: 2)
+2.years.from_now
+
+# equivalent to Time.current.advance(months: 4, years: 5)
+(4.months + 5.years).from_now
+```
+
+WARNING. For other durations please refer to the time extensions to `Numeric`.
+
+NOTE: Defined in `active_support/core_ext/integer/time.rb`.
+
 Extensions to `BigDecimal`
 --------------------------
 ### `to_s`