update AS/core_ext docs [ci skip]

1 files changed, 31 insertions, 24 deletions

diff --git a/activesupport/lib/active_support/core_ext/date_time/calculations.rb b/activesupport/lib/active_support/core_ext/date_time/calculations.rb
index 5fb19f2e6e..385aa586bb 100644
--- a/activesupport/lib/active_support/core_ext/date_time/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/date_time/calculations.rb
@@ -9,35 +9,40 @@ class DateTime
       ::Time.local(2012).utc_offset.to_r / 86400
     end
 
-    # Returns <tt>Time.zone.now.to_datetime</tt> when <tt>Time.zone</tt> or <tt>config.time_zone</tt> are set, otherwise returns <tt>Time.now.to_datetime</tt>.
+    # Returns <tt>Time.zone.now.to_datetime</tt> when <tt>Time.zone</tt> or
+    # <tt>config.time_zone</tt> are set, otherwise returns
+    # <tt>Time.now.to_datetime</tt>.
     def current
       ::Time.zone ? ::Time.zone.now.to_datetime : ::Time.now.to_datetime
     end
   end
 
-  # Tells whether the DateTime object's datetime lies in the past
+  # Tells whether the DateTime object's datetime lies in the past.
   def past?
     self < ::DateTime.current
   end
 
-  # Tells whether the DateTime object's datetime lies in the future
+  # Tells whether the DateTime object's datetime lies in the future.
   def future?
     self > ::DateTime.current
   end
 
-  # Seconds since midnight: DateTime.now.seconds_since_midnight
+  # Seconds since midnight: DateTime.now.seconds_since_midnight.
   def seconds_since_midnight
     sec + (min * 60) + (hour * 3600)
   end
 
-  # Returns a new DateTime where one or more of the elements have been changed according to the +options+ parameter. The time options
-  # (<tt>:hour</tt>, <tt>:minute</tt>, <tt>:sec</tt>) reset cascadingly, so if only the hour is passed, then minute and sec is set to 0. If the hour and
-  # minute is passed, then sec is set to 0.  The +options+ parameter takes a hash with any of these keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>,
-  # <tt>:hour</tt>, <tt>:min</tt>, <tt>:sec</tt>, <tt>:offset</tt>, <tt>:start</tt>.
+  # Returns a new DateTime where one or more of the elements have been changed
+  # according to the +options+ parameter. The time options (<tt>:hour</tt>,
+  # <tt>:minute</tt>, <tt>:sec</tt>) reset cascadingly, so if only the hour is
+  # passed, then minute and sec is set to 0. If the hour and minute is passed,
+  # then sec is set to 0. The +options+ parameter takes a hash with any of these
+  # keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>, <tt>:hour</tt>,
+  # <tt>:min</tt>, <tt>:sec</tt>, <tt>:offset</tt>, <tt>:start</tt>.
   #
-  #   DateTime.new(2012, 8, 29, 22, 35, 0).change(:day => 1)                  # => DateTime.new(2012, 8, 1, 22, 35, 0)
-  #   DateTime.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :day => 1)   # => DateTime.new(1981, 8, 1, 22, 35, 0)
-  #   DateTime.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :hour => 0)  # => DateTime.new(1981, 8, 29, 0, 0, 0)
+  #   DateTime.new(2012, 8, 29, 22, 35, 0).change(day: 1)              # => DateTime.new(2012, 8, 1, 22, 35, 0)
+  #   DateTime.new(2012, 8, 29, 22, 35, 0).change(year: 1981, day: 1)  # => DateTime.new(1981, 8, 1, 22, 35, 0)
+  #   DateTime.new(2012, 8, 29, 22, 35, 0).change(year: 1981, hour: 0) # => DateTime.new(1981, 8, 29, 0, 0, 0)
   def change(options)
     ::DateTime.civil(
       options.fetch(:year, year),
@@ -70,20 +75,21 @@ class DateTime
     end
   end
 
-  # Returns a new DateTime representing the time a number of seconds ago
+  # Returns a new DateTime representing the time a number of seconds ago.
   # Do not use this method in combination with x.months, use months_ago instead!
   def ago(seconds)
     since(-seconds)
   end
 
-  # Returns a new DateTime representing the time a number of seconds since the instance time
-  # Do not use this method in combination with x.months, use months_since instead!
+  # Returns a new DateTime representing the time a number of seconds since the
+  # instance time. Do not use this method in combination with x.months, use
+  # months_since instead!
   def since(seconds)
     self + Rational(seconds.round, 86400)
   end
   alias :in :since
 
-  # Returns a new DateTime representing the start of the day (0:00)
+  # Returns a new DateTime representing the start of the day (0:00).
   def beginning_of_day
     change(:hour => 0)
   end
@@ -91,42 +97,43 @@ class DateTime
   alias :at_midnight :beginning_of_day
   alias :at_beginning_of_day :beginning_of_day
 
-  # Returns a new DateTime representing the end of the day (23:59:59)
+  # Returns a new DateTime representing the end of the day (23:59:59).
   def end_of_day
     change(:hour => 23, :min => 59, :sec => 59)
   end
 
-  # Returns a new DateTime representing the start of the hour (hh:00:00)
+  # Returns a new DateTime representing the start of the hour (hh:00:00).
   def beginning_of_hour
     change(:min => 0)
   end
   alias :at_beginning_of_hour :beginning_of_hour
 
-  # Returns a new DateTime representing the end of the hour (hh:59:59)
+  # Returns a new DateTime representing the end of the hour (hh:59:59).
   def end_of_hour
     change(:min => 59, :sec => 59)
   end
 
-  # Adjusts DateTime to UTC by adding its offset value; offset is set to 0
+  # Adjusts DateTime to UTC by adding its offset value; offset is set to 0.
   #
-  #   DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24))       # => Mon, 21 Feb 2005 10:11:12 -0600
-  #   DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24)).utc   # => Mon, 21 Feb 2005 16:11:12 +0000
+  #   DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24))     # => Mon, 21 Feb 2005 10:11:12 -0600
+  #   DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24)).utc # => Mon, 21 Feb 2005 16:11:12 +0000
   def utc
     new_offset(0)
   end
   alias_method :getutc, :utc
 
-  # Returns true if offset == 0
+  # Returns +true+ if <tt>offset == 0</tt>.
   def utc?
     offset == 0
   end
 
-  # Returns the offset value in seconds
+  # Returns the offset value in seconds.
   def utc_offset
     (offset * 86400).to_i
   end
 
-  # Layers additional behavior on DateTime#<=> so that Time and ActiveSupport::TimeWithZone instances can be compared with a DateTime
+  # Layers additional behavior on DateTime#<=> so that Time and
+  # ActiveSupport::TimeWithZone instances can be compared with a DateTime.
   def <=>(other)
     super other.to_datetime
   end