update AS/core_ext docs [ci skip]

29 files changed, 121 insertions, 113 deletions

diff --git a/activesupport/lib/active_support/core_ext/array/conversions.rb b/activesupport/lib/active_support/core_ext/array/conversions.rb
index d6ae031c0d..7f37c459c1 100644
--- a/activesupport/lib/active_support/core_ext/array/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/array/conversions.rb
@@ -142,7 +142,7 @@ class Array
   #
   # Otherwise the root element is "objects":
   #
-  #   [{:foo => 1, :bar => 2}, {:baz => 3}].to_xml
+  #   [{ foo: 1, bar: 2}, { baz: 3}].to_xml
   #
   #   <?xml version="1.0" encoding="UTF-8"?>
   #   <objects type="array">
@@ -164,7 +164,7 @@ class Array
   #
   # To ensure a meaningful root element use the <tt>:root</tt> option:
   #
-  #   customer_with_no_projects.projects.to_xml(:root => "projects")
+  #   customer_with_no_projects.projects.to_xml(root: 'projects')
   #
   #   <?xml version="1.0" encoding="UTF-8"?>
   #   <projects type="array"/>
@@ -174,7 +174,7 @@ class Array
   #
   # The +options+ hash is passed downwards:
   #
-  #   Message.all.to_xml(:skip_types => true)
+  #   Message.all.to_xml(skip_types: true)
   #
   #   <?xml version="1.0" encoding="UTF-8"?>
   #   <messages>
diff --git a/activesupport/lib/active_support/core_ext/array/extract_options.rb b/activesupport/lib/active_support/core_ext/array/extract_options.rb
index 40ceb3eb9e..9008a0df2a 100644
--- a/activesupport/lib/active_support/core_ext/array/extract_options.rb
+++ b/activesupport/lib/active_support/core_ext/array/extract_options.rb
@@ -17,8 +17,8 @@ class Array
   #     args.extract_options!
   #   end
   #
-  #   options(1, 2)           # => {}
-  #   options(1, 2, :a => :b) # => {:a=>:b}
+  #   options(1, 2)        # => {}
+  #   options(1, 2, a: :b) # => {:a=>:b}
   def extract_options!
     if last.is_a?(Hash) && last.extractable_options?
       pop
diff --git a/activesupport/lib/active_support/core_ext/array/grouping.rb b/activesupport/lib/active_support/core_ext/array/grouping.rb
index a184eb492a..f79b100b3b 100644
--- a/activesupport/lib/active_support/core_ext/array/grouping.rb
+++ b/activesupport/lib/active_support/core_ext/array/grouping.rb
@@ -83,8 +83,8 @@ class Array
   # Divides the array into one or more subarrays based on a delimiting +value+
   # or the result of an optional block.
   #
-  #   [1, 2, 3, 4, 5].split(3)                # => [[1, 2], [4, 5]]
-  #   (1..10).to_a.split { |i| i % 3 == 0 }   # => [[1, 2], [4, 5], [7, 8], [10]]
+  #   [1, 2, 3, 4, 5].split(3)              # => [[1, 2], [4, 5]]
+  #   (1..10).to_a.split { |i| i % 3 == 0 } # => [[1, 2], [4, 5], [7, 8], [10]]
   def split(value = nil, &block)
     inject([[]]) do |results, element|
       if block && block.call(element) || value == element
diff --git a/activesupport/lib/active_support/core_ext/array/uniq_by.rb b/activesupport/lib/active_support/core_ext/array/uniq_by.rb
index 3bedfa9a61..c1d5a355a4 100644
--- a/activesupport/lib/active_support/core_ext/array/uniq_by.rb
+++ b/activesupport/lib/active_support/core_ext/array/uniq_by.rb
@@ -4,7 +4,6 @@ class Array
   # Returns a unique array based on the criteria in the block.
   #
   #   [1, 2, 3, 4].uniq_by { |i| i.odd? } # => [1, 2]
-  #
   def uniq_by(&block)
     ActiveSupport::Deprecation.warn 'uniq_by is deprecated. Use Array#uniq instead', caller
     uniq(&block)
diff --git a/activesupport/lib/active_support/core_ext/array/wrap.rb b/activesupport/lib/active_support/core_ext/array/wrap.rb
index 9ea93d7226..55582c6487 100644
--- a/activesupport/lib/active_support/core_ext/array/wrap.rb
+++ b/activesupport/lib/active_support/core_ext/array/wrap.rb
@@ -22,8 +22,8 @@ class Array
   #
   # The last point is particularly worth comparing for some enumerables:
   #
-  #   Array(:foo => :bar)      # => [[:foo, :bar]]
-  #   Array.wrap(:foo => :bar) # => [{:foo => :bar}]
+  #   Array(foo: :bar)      # => [[:foo, :bar]]
+  #   Array.wrap(foo: :bar) # => [{:foo => :bar}]
   #
   # There's also a related idiom that uses the splat operator:
   #
diff --git a/activesupport/lib/active_support/core_ext/class/attribute.rb b/activesupport/lib/active_support/core_ext/class/attribute.rb
index 7b6f8ab0a1..1c3d26ead4 100644
--- a/activesupport/lib/active_support/core_ext/class/attribute.rb
+++ b/activesupport/lib/active_support/core_ext/class/attribute.rb
@@ -57,16 +57,16 @@ class Class
   #   object.setting          # => false
   #   Base.setting            # => true
   #
-  # To opt out of the instance reader method, pass :instance_reader => false.
+  # To opt out of the instance reader method, pass <tt>instance_reader: false</tt>.
   #
   #   object.setting          # => NoMethodError
   #   object.setting?         # => NoMethodError
   #
-  # To opt out of the instance writer method, pass :instance_writer => false.
+  # To opt out of the instance writer method, pass <tt>instance_writer: false</tt>.
   #
   #   object.setting = false  # => NoMethodError
   #
-  # To opt out of both instance methods, pass :instance_accessor => false.
+  # To opt out of both instance methods, pass <tt>instance_accessor: false</tt>.
   def class_attribute(*attrs)
     options = attrs.extract_options!
     instance_reader = options.fetch(:instance_accessor, true) && options.fetch(:instance_reader, true)
diff --git a/activesupport/lib/active_support/core_ext/date/calculations.rb b/activesupport/lib/active_support/core_ext/date/calculations.rb
index 86badf4d29..c6eec9c486 100644
--- a/activesupport/lib/active_support/core_ext/date/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/date/calculations.rb
@@ -86,8 +86,8 @@ class Date
   # Returns a new Date where one or more of the elements have been changed according to the +options+ parameter.
   # The +options+ parameter is a hash with a combination of these keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>.
   #
-  #   Date.new(2007, 5, 12).change(:day => 1)                  # => Date.new(2007, 5, 1)
-  #   Date.new(2007, 5, 12).change(:year => 2005, :month => 1) # => Date.new(2005, 1, 12)
+  #   Date.new(2007, 5, 12).change(day: 1)               # => Date.new(2007, 5, 1)
+  #   Date.new(2007, 5, 12).change(year: 2005, month: 1) # => Date.new(2005, 1, 12)
   def change(options)
     ::Date.new(
       options.fetch(:year, year),
diff --git a/activesupport/lib/active_support/core_ext/date/conversions.rb b/activesupport/lib/active_support/core_ext/date/conversions.rb
index 81f969e786..9120b0ba49 100644
--- a/activesupport/lib/active_support/core_ext/date/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/date/conversions.rb
@@ -43,7 +43,7 @@ class Date
   #
   #   # config/initializers/time_formats.rb
   #   Date::DATE_FORMATS[:month_and_year] = '%B %Y'
-  #   Date::DATE_FORMATS[:short_ordinal] = lambda { |date| date.strftime("%B #{date.day.ordinalize}") }
+  #   Date::DATE_FORMATS[:short_ordinal] = ->(date) { date.strftime("%B #{date.day.ordinalize}") }
   def to_formatted_s(format = :default)
     if formatter = DATE_FORMATS[format]
       if formatter.respond_to?(:call)
diff --git a/activesupport/lib/active_support/core_ext/date/zones.rb b/activesupport/lib/active_support/core_ext/date/zones.rb
index a70b47b7bc..c1b3934722 100644
--- a/activesupport/lib/active_support/core_ext/date/zones.rb
+++ b/activesupport/lib/active_support/core_ext/date/zones.rb
@@ -2,8 +2,9 @@ require 'date'
 require 'active_support/core_ext/time/zones'
 
 class Date
-  # Converts Date to a TimeWithZone in the current zone if Time.zone or Time.zone_default
-  # is set, otherwise converts Date to a Time via Date#to_time
+  # Converts Date to a TimeWithZone in the current zone if <tt>Time.zone</tt> or
+  # <tt>Time.zone_default</tt> is set, otherwise converts Date to a Time via
+  # Date#to_time.
   def to_time_in_current_zone
     if ::Time.zone
       ::Time.zone.local(year, month, day)
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
diff --git a/activesupport/lib/active_support/core_ext/date_time/conversions.rb b/activesupport/lib/active_support/core_ext/date_time/conversions.rb
index 7c3a5eaace..b7d8414a9d 100644
--- a/activesupport/lib/active_support/core_ext/date_time/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/date_time/conversions.rb
@@ -53,7 +53,8 @@ class DateTime
   alias_method :default_inspect, :inspect
   alias_method :inspect, :readable_inspect
 
-  # Returns DateTime with local offset for given year if format is local else offset is zero
+  # Returns DateTime with local offset for given year if format is local else
+  # offset is zero.
   #
   #   DateTime.civil_from_format :local, 2012
   #   # => Sun, 01 Jan 2012 00:00:00 +0300
@@ -68,12 +69,12 @@ class DateTime
     civil(year, month, day, hour, min, sec, offset)
   end
 
-  # Converts self to a floating-point number of seconds since the Unix epoch.
+  # Converts +self+ to a floating-point number of seconds since the Unix epoch.
   def to_f
     seconds_since_unix_epoch.to_f
   end
 
-  # Converts self to an integer number of seconds since the Unix epoch.
+  # Converts +self+ to an integer number of seconds since the Unix epoch.
   def to_i
     seconds_since_unix_epoch.to_i
   end
diff --git a/activesupport/lib/active_support/core_ext/date_time/zones.rb b/activesupport/lib/active_support/core_ext/date_time/zones.rb
index 823735d3e2..6457ffbaf6 100644
--- a/activesupport/lib/active_support/core_ext/date_time/zones.rb
+++ b/activesupport/lib/active_support/core_ext/date_time/zones.rb
@@ -6,13 +6,14 @@ class DateTime
   #   Time.zone = 'Hawaii'             # => 'Hawaii'
   #   DateTime.new(2000).in_time_zone  # => Fri, 31 Dec 1999 14:00:00 HST -10:00
   #
-  # This method is similar to Time#localtime, except that it uses <tt>Time.zone</tt> as the local zone
-  # instead of the operating system's time zone.
+  # This method is similar to Time#localtime, except that it uses <tt>Time.zone</tt>
+  # as the local zone instead of the operating system's time zone.
   #
-  # You can also pass in a TimeZone instance or string that identifies a TimeZone as an argument,
-  # and the conversion will be based on that zone instead of <tt>Time.zone</tt>.
+  # You can also pass in a TimeZone instance or string that identifies a TimeZone
+  # as an argument, and the conversion will be based on that zone instead of
+  # <tt>Time.zone</tt>.
   #
-  #   DateTime.new(2000).in_time_zone('Alaska')  # => Fri, 31 Dec 1999 15:00:00 AKST -09:00
+  #   DateTime.new(2000).in_time_zone('Alaska') # => Fri, 31 Dec 1999 15:00:00 AKST -09:00
   def in_time_zone(zone = ::Time.zone)
     if zone
       ActiveSupport::TimeWithZone.new(utc? ? self : getutc, ::Time.find_zone!(zone))
diff --git a/activesupport/lib/active_support/core_ext/enumerable.rb b/activesupport/lib/active_support/core_ext/enumerable.rb
index 03efe6a19a..4501b7ff58 100644
--- a/activesupport/lib/active_support/core_ext/enumerable.rb
+++ b/activesupport/lib/active_support/core_ext/enumerable.rb
@@ -17,7 +17,6 @@ module Enumerable
   # The default sum of an empty list is zero. You can override this default:
   #
   #  [].sum(Payment.new(0)) { |i| i.amount } # => Payment.new(0)
-  #
   def sum(identity = 0, &block)
     if block_given?
       map(&block).sum(identity)
@@ -32,7 +31,6 @@ module Enumerable
   #     => { "nextangle" => <Person ...>, "chade-" => <Person ...>, ...}
   #   people.index_by { |person| "#{person.first_name} #{person.last_name}" }
   #     => { "Chade- Fowlersburg-e" => <Person ...>, "David Heinemeier Hansson" => <Person ...>, ...}
-  #
   def index_by
     if block_given?
       Hash[map { |elem| [yield(elem), elem] }]
@@ -41,8 +39,10 @@ module Enumerable
     end
   end
 
-  # Returns true if the enumerable has more than 1 element. Functionally equivalent to enum.to_a.size > 1.
-  # Can be called with a block too, much like any?, so <tt>people.many? { |p| p.age > 26 }</tt> returns true if more than one person is over 26.
+  # Returns +true+ if the enumerable has more than 1 element. Functionally
+  # equivalent to <tt>enum.to_a.size > 1</tt>. Can be called with a block too,
+  # much like any?, so <tt>people.many? { |p| p.age > 26 }</tt> returns +true+
+  # if more than one person is over 26.
   def many?
     cnt = 0
     if block_given?
@@ -55,7 +55,8 @@ module Enumerable
     end
   end
 
-  # The negative of the <tt>Enumerable#include?</tt>. Returns true if the collection does not include the object.
+  # The negative of the <tt>Enumerable#include?</tt>. Returns +true+ if the
+  # collection does not include the object.
   def exclude?(object)
     !include?(object)
   end
diff --git a/activesupport/lib/active_support/core_ext/hash/conversions.rb b/activesupport/lib/active_support/core_ext/hash/conversions.rb
index 7c72ead36c..5ba8197006 100644
--- a/activesupport/lib/active_support/core_ext/hash/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/hash/conversions.rb
@@ -40,7 +40,7 @@ class Hash
   #       end
   #     end
   #
-  #     {:foo => Foo.new}.to_xml(:skip_instruct => true)
+  #     { foo: Foo.new }.to_xml(skip_instruct: true)
   #     # => "<hash><bar>fooing!</bar></hash>"
   #
   # * Otherwise, a node with +key+ as tag is created with a string representation of
diff --git a/activesupport/lib/active_support/core_ext/hash/deep_merge.rb b/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
index 023bf68a87..485f88cc06 100644
--- a/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
+++ b/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
@@ -1,8 +1,8 @@
 class Hash
   # Returns a new hash with +self+ and +other_hash+ merged recursively.
   #
-  #   h1 = {x: {y: [4,5,6]}, z: [7,8,9]}
-  #   h2 = {x: {y: [7,8,9]}, z: "xyz"}
+  #   h1 = { x: { y: [4,5,6] }, z: [7,8,9] }
+  #   h2 = { x: { y: [7,8,9] }, z: 'xyz' }
   #
   #   h1.deep_merge(h2) #=> {:x => {:y => [7, 8, 9]}, :z => "xyz"}
   #   h2.deep_merge(h1) #=> {:x => {:y => [4, 5, 6]}, :z => [7, 8, 9]}
diff --git a/activesupport/lib/active_support/core_ext/hash/except.rb b/activesupport/lib/active_support/core_ext/hash/except.rb
index c82da3c6c2..5cb00d0ebd 100644
--- a/activesupport/lib/active_support/core_ext/hash/except.rb
+++ b/activesupport/lib/active_support/core_ext/hash/except.rb
@@ -3,7 +3,6 @@ class Hash
   # limiting a set of parameters to everything but a few known toggles:
   #
   #   @person.update_attributes(params[:person].except(:admin))
-  #
   def except(*keys)
     dup.except!(*keys)
   end
diff --git a/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb b/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb
index 7d54c9fae6..83fe982f33 100644
--- a/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb
+++ b/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb
@@ -4,8 +4,7 @@ class Hash
 
   # Returns an <tt>ActiveSupport::HashWithIndifferentAccess</tt> out of its receiver:
   #
-  #   {:a => 1}.with_indifferent_access["a"] # => 1
-  #
+  #   { a: 1}.with_indifferent_access['a'] # => 1
   def with_indifferent_access
     ActiveSupport::HashWithIndifferentAccess.new_from_hash_copying_default(self)
   end
@@ -17,8 +16,7 @@ class Hash
   # converting to an <tt>ActiveSupport::HashWithIndifferentAccess</tt> would not be
   # desirable.
   #
-  #   b = {:b => 1}
-  #   {:a => b}.with_indifferent_access["a"] # calls b.nested_under_indifferent_access
-  #
+  #   b = { b: 1 }
+  #   { a: b }.with_indifferent_access['a'] # calls b.nested_under_indifferent_access
   alias nested_under_indifferent_access with_indifferent_access
 end
diff --git a/activesupport/lib/active_support/core_ext/hash/keys.rb b/activesupport/lib/active_support/core_ext/hash/keys.rb
index e753e36124..509dbae596 100644
--- a/activesupport/lib/active_support/core_ext/hash/keys.rb
+++ b/activesupport/lib/active_support/core_ext/hash/keys.rb
@@ -14,7 +14,7 @@ class Hash
   end
 
   # Destructively convert all keys using the block operations.
-  # Same as transform_keys but modifies +self+
+  # Same as transform_keys but modifies +self+.
   def transform_keys!
     keys.each do |key|
       self[yield(key)] = delete(key)
@@ -57,13 +57,13 @@ class Hash
   end
   alias_method :to_options!, :symbolize_keys!
 
-  # Validate all keys in a hash match *valid keys, raising ArgumentError on a mismatch.
-  # Note that keys are NOT treated indifferently, meaning if you use strings for keys but assert symbols
-  # as keys, this will fail.
+  # Validate all keys in a hash match <tt>*valid_keys</tt>, raising ArgumentError
+  # on a mismatch. Note that keys are NOT treated indifferently, meaning if you
+  # use strings for keys but assert symbols as keys, this will fail.
   #
-  #   { :name => 'Rob', :years => '28' }.assert_valid_keys(:name, :age) # => raises "ArgumentError: Unknown key: years"
-  #   { :name => 'Rob', :age => '28' }.assert_valid_keys('name', 'age') # => raises "ArgumentError: Unknown key: name"
-  #   { :name => 'Rob', :age => '28' }.assert_valid_keys(:name, :age) # => passes, raises nothing
+  #   { name: 'Rob', years: '28' }.assert_valid_keys(:name, :age) # => raises "ArgumentError: Unknown key: years"
+  #   { name: 'Rob', age: '28' }.assert_valid_keys('name', 'age') # => raises "ArgumentError: Unknown key: name"
+  #   { name: 'Rob', age: '28' }.assert_valid_keys(:name, :age) # => passes, raises nothing
   def assert_valid_keys(*valid_keys)
     valid_keys.flatten!
     each_key do |k|
diff --git a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
index 6074103484..f578ff10fc 100644
--- a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
+++ b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
@@ -1,11 +1,11 @@
 class Hash
   # Merges the caller into +other_hash+. For example,
   #
-  #   options = options.reverse_merge(:size => 25, :velocity => 10)
+  #   options = options.reverse_merge(size: 25, velocity: 10)
   #
   # is equivalent to
   #
-  #   options = {:size => 25, :velocity => 10}.merge(options)
+  #   options = { size: 25, velocity: 10}.merge(options)
   #
   # This is particularly useful for initializing an options hash
   # with default values.
diff --git a/activesupport/lib/active_support/core_ext/hash/slice.rb b/activesupport/lib/active_support/core_ext/hash/slice.rb
index b862b5ae2a..f0c78656f2 100644
--- a/activesupport/lib/active_support/core_ext/hash/slice.rb
+++ b/activesupport/lib/active_support/core_ext/hash/slice.rb
@@ -19,7 +19,9 @@ class Hash
 
   # Replaces the hash with only the given keys.
   # Returns a hash containing the removed key/value pairs.
-  #   {:a => 1, :b => 2, :c => 3, :d => 4}.slice!(:a, :b) # => {:c => 3, :d => 4}
+  #
+  #   { a: 1, b: 2, c: 3, d: 4 }.slice!(:a, :b)
+  #   # => {:c => 3, :d => 4}
   def slice!(*keys)
     keys.map! { |key| convert_key(key) } if respond_to?(:convert_key, true)
     omit = slice(*self.keys - keys)
@@ -29,7 +31,9 @@ class Hash
   end
 
   # Removes and returns the key/value pairs matching the given keys.
-  #   {:a => 1, :b => 2, :c => 3, :d => 4}.extract!(:a, :b) # => {:a => 1, :b => 2}
+  #
+  #   { a: 1, b: 2, c: 3, d: 4 }.extract!(:a, :b)
+  #   # => {:a => 1, :b => 2}
   def extract!(*keys)
     keys.each_with_object({}) { |key, result| result[key] = delete(key) }
   end
diff --git a/activesupport/lib/active_support/core_ext/integer/inflections.rb b/activesupport/lib/active_support/core_ext/integer/inflections.rb
index 1e30687166..56f2ed5985 100644
--- a/activesupport/lib/active_support/core_ext/integer/inflections.rb
+++ b/activesupport/lib/active_support/core_ext/integer/inflections.rb
@@ -10,7 +10,6 @@ class Integer
   #  1003.ordinalize  # => "1003rd"
   #  -11.ordinalize   # => "-11th"
   #  -1001.ordinalize # => "-1001st"
-  #
   def ordinalize
     ActiveSupport::Inflector.ordinalize(self)
   end
@@ -24,7 +23,6 @@ class Integer
   #  1003.ordinal  # => "rd"
   #  -11.ordinal   # => "th"
   #  -1001.ordinal # => "st"
-  #
   def ordinal
     ActiveSupport::Inflector.ordinal(self)
   end
diff --git a/activesupport/lib/active_support/core_ext/integer/time.rb b/activesupport/lib/active_support/core_ext/integer/time.rb
index 894b5d0696..9fb4f6b73a 100644
--- a/activesupport/lib/active_support/core_ext/integer/time.rb
+++ b/activesupport/lib/active_support/core_ext/integer/time.rb
@@ -1,21 +1,23 @@
 class Integer
-  # Enables the use of time calculations and declarations, like 45.minutes + 2.hours + 4.years.
+  # Enables the use of time calculations and declarations, like <tt>45.minutes +
+  # 2.hours + 4.years</tt>.
   #
-  # 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:
+  # These methods use Time#advance for precise date calculations when using
+  # <tt>from_now</tt>, +ago+, etc. as well as adding or subtracting their
+  # results from a Time object.
   #
-  #   # equivalent to Time.now.advance(:months => 1)
+  #   # equivalent to Time.now.advance(months: 1)
   #   1.month.from_now
   #
-  #   # equivalent to Time.now.advance(:years => 2)
+  #   # equivalent to Time.now.advance(years: 2)
   #   2.years.from_now
   #
-  #   # equivalent to Time.now.advance(:months => 4, :years => 5)
+  #   # equivalent to Time.now.advance(months: 4, years: 5)
   #   (4.months + 5.years).from_now
   #
-  # While these methods provide precise calculation when used as in the examples above, care
-  # should be taken to note that this is not true if the result of `months', `years', etc is
-  # converted before use:
+  # While these methods provide precise calculation when used as in the examples
+  # above, care should be taken to note that this is not true if the result of
+  # +months+, +years+, etc is converted before use:
   #
   #   # equivalent to 30.days.to_i.from_now
   #   1.month.to_i.from_now
diff --git a/activesupport/lib/active_support/core_ext/kernel/reporting.rb b/activesupport/lib/active_support/core_ext/kernel/reporting.rb
index ad3f9ebec9..bc97da6ef2 100644
--- a/activesupport/lib/active_support/core_ext/kernel/reporting.rb
+++ b/activesupport/lib/active_support/core_ext/kernel/reporting.rb
@@ -1,7 +1,8 @@
 require 'rbconfig'
 
 module Kernel
-  # Sets $VERBOSE to nil for the duration of the block and back to its original value afterwards.
+  # Sets $VERBOSE to nil for the duration of the block and back to its original
+  # value afterwards.
   #
   #   silence_warnings do
   #     value = noisy_call # no warning voiced
@@ -12,12 +13,14 @@ module Kernel
     with_warnings(nil) { yield }
   end
 
-  # Sets $VERBOSE to true for the duration of the block and back to its original value afterwards.
+  # Sets $VERBOSE to +true+ for the duration of the block and back to its
+  # original value afterwards.
   def enable_warnings
     with_warnings(true) { yield }
   end
 
-  # Sets $VERBOSE for the duration of the block and back to its original value afterwards.
+  # Sets $VERBOSE for the duration of the block and back to its original
+  # value afterwards.
   def with_warnings(flag)
     old_verbose, $VERBOSE = $VERBOSE, flag
     yield
@@ -65,7 +68,6 @@ module Kernel
   #
   #   stream = capture(:stdout) { puts 'Cool' }
   #   stream # => "Cool\n"
-  #
   def capture(stream)
     begin
       stream = stream.to_s
@@ -83,7 +85,6 @@ module Kernel
   # Silences both STDOUT and STDERR, even for subprocesses.
   #
   #   quietly { system 'bundle install' }
-  #
   def quietly
     silence_stream(STDOUT) do
       silence_stream(STDERR) do
diff --git a/activesupport/lib/active_support/core_ext/module/anonymous.rb b/activesupport/lib/active_support/core_ext/module/anonymous.rb
index 0a9e791030..b0c7b021db 100644
--- a/activesupport/lib/active_support/core_ext/module/anonymous.rb
+++ b/activesupport/lib/active_support/core_ext/module/anonymous.rb
@@ -13,7 +13,6 @@ class Module
   #   m = Module.new # creates an anonymous module
   #   M = m          # => m gets a name here as a side-effect
   #   m.name         # => "M"
-  #
   def anonymous?
     name.nil?
   end
diff --git a/activesupport/lib/active_support/core_ext/module/introspection.rb b/activesupport/lib/active_support/core_ext/module/introspection.rb
index 3c8e811fa4..649a969149 100644
--- a/activesupport/lib/active_support/core_ext/module/introspection.rb
+++ b/activesupport/lib/active_support/core_ext/module/introspection.rb
@@ -27,7 +27,6 @@ class Module
   #
   #   M.parent          # => Object
   #   Module.new.parent # => Object
-  #
   def parent
     parent_name ? ActiveSupport::Inflector.constantize(parent_name) : Object
   end
@@ -44,7 +43,6 @@ class Module
   #   M.parents    # => [Object]
   #   M::N.parents # => [M, Object]
   #   X.parents    # => [M, Object]
-  #
   def parents
     parents = []
     if parent_name
diff --git a/activesupport/lib/active_support/core_ext/string/filters.rb b/activesupport/lib/active_support/core_ext/string/filters.rb
index 8644529806..e05447439a 100644
--- a/activesupport/lib/active_support/core_ext/string/filters.rb
+++ b/activesupport/lib/active_support/core_ext/string/filters.rb
@@ -24,16 +24,16 @@ class String
   #
   # Pass a string or regexp <tt>:separator</tt> to truncate +text+ at a natural break:
   #
-  #   'Once upon a time in a world far far away'.truncate(27, :separator => ' ')
+  #   'Once upon a time in a world far far away'.truncate(27, separator: ' ')
   #   # => "Once upon a time in a..."
   #
-  #   'Once upon a time in a world far far away'.truncate(27, :separator => /\s/)
+  #   'Once upon a time in a world far far away'.truncate(27, separator: /\s/)
   #   # => "Once upon a time in a..."
   #
   # The last characters will be replaced with the <tt>:omission</tt> string (defaults to "...")
   # for a total length not exceeding <tt>length</tt>:
   #
-  #   'And they found that many people were sleeping better.'.truncate(25, :omission => '... (continued)')
+  #   'And they found that many people were sleeping better.'.truncate(25, omission: '... (continued)')
   #   # => "And they f... (continued)"
   def truncate(truncate_at, options = {})
     return dup unless length > truncate_at
diff --git a/activesupport/lib/active_support/core_ext/string/output_safety.rb b/activesupport/lib/active_support/core_ext/string/output_safety.rb
index dad4b29d46..7d9e5bbe7d 100644
--- a/activesupport/lib/active_support/core_ext/string/output_safety.rb
+++ b/activesupport/lib/active_support/core_ext/string/output_safety.rb
@@ -59,7 +59,6 @@ class ERB
     #
     #   json_escape('{"name":"john","created_at":"2010-04-28T01:39:31Z","id":1}')
     #   # => {name:john,created_at:2010-04-28T01:39:31Z,id:1}
-    #
     def json_escape(s)
       result = s.to_s.gsub(JSON_ESCAPE_REGEXP) { |special| JSON_ESCAPE[special] }
       s.html_safe? ? result.html_safe : result
diff --git a/activesupport/lib/active_support/core_ext/time/conversions.rb b/activesupport/lib/active_support/core_ext/time/conversions.rb
index 10ca26acf2..48654eb1cc 100644
--- a/activesupport/lib/active_support/core_ext/time/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/time/conversions.rb
@@ -23,17 +23,17 @@ class Time
   #
   # This method is aliased to <tt>to_s</tt>.
   #
-  #   time = Time.now                     # => Thu Jan 18 06:10:17 CST 2007
+  #   time = Time.now                    # => Thu Jan 18 06:10:17 CST 2007
   #
-  #   time.to_formatted_s(:time)          # => "06:10"
-  #   time.to_s(:time)                    # => "06:10"
+  #   time.to_formatted_s(:time)         # => "06:10"
+  #   time.to_s(:time)                   # => "06:10"
   #
-  #   time.to_formatted_s(:db)            # => "2007-01-18 06:10:17"
-  #   time.to_formatted_s(:number)        # => "20070118061017"
-  #   time.to_formatted_s(:short)         # => "18 Jan 06:10"
-  #   time.to_formatted_s(:long)          # => "January 18, 2007 06:10"
-  #   time.to_formatted_s(:long_ordinal)  # => "January 18th, 2007 06:10"
-  #   time.to_formatted_s(:rfc822)        # => "Thu, 18 Jan 2007 06:10:17 -0600"
+  #   time.to_formatted_s(:db)           # => "2007-01-18 06:10:17"
+  #   time.to_formatted_s(:number)       # => "20070118061017"
+  #   time.to_formatted_s(:short)        # => "18 Jan 06:10"
+  #   time.to_formatted_s(:long)         # => "January 18, 2007 06:10"
+  #   time.to_formatted_s(:long_ordinal) # => "January 18th, 2007 06:10"
+  #   time.to_formatted_s(:rfc822)       # => "Thu, 18 Jan 2007 06:10:17 -0600"
   #
   # == Adding your own time formats to +to_formatted_s+
   # You can add your own formats to the Time::DATE_FORMATS hash.
@@ -42,7 +42,7 @@ class Time
   #
   #   # config/initializers/time_formats.rb
   #   Time::DATE_FORMATS[:month_and_year] = '%B %Y'
-  #   Time::DATE_FORMATS[:short_ordinal] = lambda { |time| time.strftime("%B #{time.day.ordinalize}") }
+  #   Time::DATE_FORMATS[:short_ordinal]  = ->(time) { time.strftime("%B #{time.day.ordinalize}") }
   def to_formatted_s(format = :default)
     if formatter = DATE_FORMATS[format]
       formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter)
@@ -55,8 +55,8 @@ class Time
 
   # Returns the UTC offset as an +HH:MM formatted string.
   #
-  #   Time.local(2000).formatted_offset         # => "-06:00"
-  #   Time.local(2000).formatted_offset(false)  # => "-0600"
+  #   Time.local(2000).formatted_offset        # => "-06:00"
+  #   Time.local(2000).formatted_offset(false) # => "-0600"
   def formatted_offset(colon = true, alternate_utc_string = nil)
     utc? && alternate_utc_string || ActiveSupport::TimeZone.seconds_to_utc_offset(utc_offset, colon)
   end
diff --git a/activesupport/lib/active_support/core_ext/time/zones.rb b/activesupport/lib/active_support/core_ext/time/zones.rb
index 37bc3fae24..139d48f59c 100644
--- a/activesupport/lib/active_support/core_ext/time/zones.rb
+++ b/activesupport/lib/active_support/core_ext/time/zones.rb
@@ -76,8 +76,8 @@ class Time
 
   # Returns the simultaneous time in <tt>Time.zone</tt>.
   #
-  #   Time.zone = 'Hawaii'         # => 'Hawaii'
-  #   Time.utc(2000).in_time_zone  # => Fri, 31 Dec 1999 14:00:00 HST -10:00
+  #   Time.zone = 'Hawaii'        # => 'Hawaii'
+  #   Time.utc(2000).in_time_zone # => Fri, 31 Dec 1999 14:00:00 HST -10:00
   #
   # This method is similar to Time#localtime, except that it uses <tt>Time.zone</tt> as the local zone
   # instead of the operating system's time zone.
@@ -85,7 +85,7 @@ class Time
   # You can also pass in a TimeZone instance or string that identifies a TimeZone as an argument,
   # and the conversion will be based on that zone instead of <tt>Time.zone</tt>.
   #
-  #   Time.utc(2000).in_time_zone('Alaska')  # => Fri, 31 Dec 1999 15:00:00 AKST -09:00
+  #   Time.utc(2000).in_time_zone('Alaska') # => Fri, 31 Dec 1999 15:00:00 AKST -09:00
   def in_time_zone(zone = ::Time.zone)
     if zone
       ActiveSupport::TimeWithZone.new(utc? ? self : getutc, ::Time.find_zone!(zone))