Merge branch 'master' of github.com:rails/docrails

8 files changed, 72 insertions, 7 deletions

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 763d563231..9c9faf67ea 100644
--- a/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
+++ b/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
@@ -4,7 +4,7 @@ class Hash
   #   h1 = { a: true, b: { c: [1, 2, 3] } }
   #   h2 = { a: false, b: { x: [3, 4, 5] } }
   #
-  #   h1.deep_merge(h2) #=> { a: false, b: { c: [1, 2, 3], x: [3, 4, 5] } }
+  #   h1.deep_merge(h2) # => { a: false, b: { c: [1, 2, 3], x: [3, 4, 5] } }
   #
   # Like with Hash#merge in the standard library, a block can be provided
   # to merge values:
diff --git a/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb b/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb
index d317df5079..d4e6b5a1ac 100644
--- a/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb
+++ b/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb
@@ -203,7 +203,7 @@ class Module
   #     include HairColors
   #   end
   #
-  #   Person.class_variable_get("@@hair_colors") #=> [:brown, :black, :blonde, :red]
+  #   Person.class_variable_get("@@hair_colors") # => [:brown, :black, :blonde, :red]
   def mattr_accessor(*syms, &blk)
     mattr_reader(*syms, &blk)
     mattr_writer(*syms, &blk)
diff --git a/activesupport/lib/active_support/core_ext/numeric/bytes.rb b/activesupport/lib/active_support/core_ext/numeric/bytes.rb
index deea8e9358..dfbca32474 100644
--- a/activesupport/lib/active_support/core_ext/numeric/bytes.rb
+++ b/activesupport/lib/active_support/core_ext/numeric/bytes.rb
@@ -7,36 +7,56 @@ class Numeric
   EXABYTE  = PETABYTE * 1024
 
   # Enables the use of byte calculations and declarations, like 45.bytes + 2.6.megabytes
+  #
+  #   2.bytes # => 2
   def bytes
     self
   end
   alias :byte :bytes
 
+  # Returns the number of bytes equivalent to the kilobytes provided.
+  #
+  #   2.kilobytes # => 2048
   def kilobytes
     self * KILOBYTE
   end
   alias :kilobyte :kilobytes
 
+  # Returns the number of bytes equivalent to the megabytes provided.
+  #
+  #   2.megabytes # => 2_097_152
   def megabytes
     self * MEGABYTE
   end
   alias :megabyte :megabytes
 
+  # Returns the number of bytes equivalent to the gigabytes provided.
+  #
+  #   2.gigabytes # => 2_147_483_648
   def gigabytes
     self * GIGABYTE
   end
   alias :gigabyte :gigabytes
 
+  # Returns the number of bytes equivalent to the terabytes provided.
+  #
+  #   2.terabytes # => 2_199_023_255_552
   def terabytes
     self * TERABYTE
   end
   alias :terabyte :terabytes
 
+  # Returns the number of bytes equivalent to the petabytes provided.
+  #
+  #   2.petabytes # => 2_251_799_813_685_248
   def petabytes
     self * PETABYTE
   end
   alias :petabyte :petabytes
 
+  # Returns the number of bytes equivalent to the exabytes provided.
+  #
+  #   2.exabytes # => 2_305_843_009_213_693_952
   def exabytes
     self * EXABYTE
   end
diff --git a/activesupport/lib/active_support/core_ext/numeric/time.rb b/activesupport/lib/active_support/core_ext/numeric/time.rb
index 689fae4830..ef32817f55 100644
--- a/activesupport/lib/active_support/core_ext/numeric/time.rb
+++ b/activesupport/lib/active_support/core_ext/numeric/time.rb
@@ -36,33 +36,51 @@ class Numeric
   end
   alias :second :seconds
 
+  # Returns a Duration instance matching the number of minutes provided.
+  #
+  #   2.minutes # => 120 seconds
   def minutes
     ActiveSupport::Duration.new(self * 60, [[:seconds, self * 60]])
   end
   alias :minute :minutes
 
+  # Returns a Duration instance matching the number of hours provided.
+  #
+  #   2.hours # => 7_200 seconds
   def hours
     ActiveSupport::Duration.new(self * 3600, [[:seconds, self * 3600]])
   end
   alias :hour :hours
 
+  # Returns a Duration instance matching the number of days provided.
+  #
+  #   2.days # => 2 days
   def days
     ActiveSupport::Duration.new(self * 24.hours, [[:days, self]])
   end
   alias :day :days
 
+  # Returns a Duration instance matching the number of weeks provided.
+  #
+  #   2.weeks # => 14 days
   def weeks
     ActiveSupport::Duration.new(self * 7.days, [[:days, self * 7]])
   end
   alias :week :weeks
 
+  # Returns a Duration instance matching the number of fortnights provided.
+  #
+  #   2.fortnights # => 28 days
   def fortnights
     ActiveSupport::Duration.new(self * 2.weeks, [[:days, self * 14]])
   end
   alias :fortnight :fortnights
 
+  # Returns the number of milliseconds equivalent to the seconds provided.
   # Used with the standard time durations, like 1.hour.in_milliseconds --
   # so we can feed them to JavaScript functions like getTime().
+  #
+  #   2.in_milliseconds # => 2_000
   def in_milliseconds
     self * 1000
   end
diff --git a/activesupport/lib/active_support/core_ext/object/try.rb b/activesupport/lib/active_support/core_ext/object/try.rb
index 56da398978..26b8d58948 100644
--- a/activesupport/lib/active_support/core_ext/object/try.rb
+++ b/activesupport/lib/active_support/core_ext/object/try.rb
@@ -21,11 +21,11 @@ class Object
   #
   # +try+ will also return +nil+ if the receiver does not respond to the method:
   #
-  #   @person.try(:non_existing_method) #=> nil
+  #   @person.try(:non_existing_method) # => nil
   #
   # instead of
   #
-  #   @person.non_existing_method if @person.respond_to?(:non_existing_method) #=> nil
+  #   @person.non_existing_method if @person.respond_to?(:non_existing_method) # => nil
   #
   # +try+ returns +nil+ when called on +nil+ regardless of whether it responds
   # to the method:
diff --git a/activesupport/lib/active_support/core_ext/thread.rb b/activesupport/lib/active_support/core_ext/thread.rb
index 4cd6634558..9637178f53 100644
--- a/activesupport/lib/active_support/core_ext/thread.rb
+++ b/activesupport/lib/active_support/core_ext/thread.rb
@@ -67,8 +67,8 @@ class Thread
   #
   #   me = Thread.current
   #   me.freeze
-  #   me.thread_variable_set(:oliver, "a")  #=> RuntimeError: can't modify frozen thread locals
-  #   me[:oliver] = "a"                     #=> RuntimeError: can't modify frozen thread locals
+  #   me.thread_variable_set(:oliver, "a")  # => RuntimeError: can't modify frozen thread locals
+  #   me[:oliver] = "a"                     # => RuntimeError: can't modify frozen thread locals
   def freeze
     _locals.freeze
     super
diff --git a/activesupport/lib/active_support/core_ext/time/zones.rb b/activesupport/lib/active_support/core_ext/time/zones.rb
index 64c3b7201b..0668eadb1e 100644
--- a/activesupport/lib/active_support/core_ext/time/zones.rb
+++ b/activesupport/lib/active_support/core_ext/time/zones.rb
@@ -51,7 +51,16 @@ class Time
       end
     end
 
-    # Returns a TimeZone instance or nil, or raises an ArgumentError for invalid timezones.
+    # Returns a TimeZone instance matching the time zone provided.
+    # Accepts the time zone in any format supported by <tt>Time.zone=</tt>.
+    # Raises an ArgumentError for invalid time zones.
+    #
+    #   Time.find_zone! "America/New_York" # => #<ActiveSupport::TimeZone @name="America/New_York" ...>
+    #   Time.find_zone! "EST"              # => #<ActiveSupport::TimeZone @name="EST" ...>
+    #   Time.find_zone! -5.hours           # => #<ActiveSupport::TimeZone @name="Bogota" ...>
+    #   Time.find_zone! nil                # => nil
+    #   Time.find_zone! false              # => false
+    #   Time.find_zone! "NOT-A-TIMEZONE"   # => ArgumentError: Invalid Timezone: NOT-A-TIMEZONE
     def find_zone!(time_zone)
       if !time_zone || time_zone.is_a?(ActiveSupport::TimeZone)
         time_zone
@@ -72,6 +81,12 @@ class Time
       raise ArgumentError, "Invalid Timezone: #{time_zone}"
     end
 
+    # Returns a TimeZone instance matching the time zone provided.
+    # Accepts the time zone in any format supported by <tt>Time.zone=</tt>.
+    # Returns +nil+ for invalid time zones.
+    #
+    #   Time.find_zone "America/New_York" # => #<ActiveSupport::TimeZone @name="America/New_York" ...>
+    #   Time.find_zone "NOT-A-TIMEZONE"   # => nil
     def find_zone(time_zone)
       find_zone!(time_zone) rescue nil
     end
diff --git a/activesupport/lib/active_support/notifications/instrumenter.rb b/activesupport/lib/active_support/notifications/instrumenter.rb
index 3a244b34b5..075ddc2382 100644
--- a/activesupport/lib/active_support/notifications/instrumenter.rb
+++ b/activesupport/lib/active_support/notifications/instrumenter.rb
@@ -57,6 +57,18 @@ module ActiveSupport
         @duration       = nil
       end
 
+      # Returns the difference in milliseconds between when the execution of the
+      # event started and when it ended.
+      #
+      #   ActiveSupport::Notifications.subscribe('wait') do |*args|
+      #     @event = ActiveSupport::Notifications::Event.new(*args)
+      #   end
+      #
+      #   ActiveSupport::Notifications.instrument('wait') do
+      #     sleep 1
+      #   end
+      #
+      #   @event.duration # => 1000.138
       def duration
         @duration ||= 1000.0 * (self.end - time)
       end