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

actionpack/lib/action_dispatch/http/url.rb

@@ -12,10 +12,22 @@ module URL
       self.tld_length = 1
 
       class << self
+        # Returns the domain part of a host given the domain level.
+        #
+        #    # Top-level domain example
+        #    extract_domain('www.example.com', 1) # => "example.com"
+        #    # Second-level domain example
+        #    extract_domain('dev.www.example.co.uk', 2) # => "example.co.uk"
         def extract_domain(host, tld_length)
           extract_domain_from(host, tld_length) if named_host?(host)
         end
 
+        # Returns the subdomains of a host as an Array given the domain level.
+        #
+        #    # Top-level domain example
+        #    extract_subdomains('www.example.com', 1) # => ["www"]
+        #    # Second-level domain example
+        #    extract_subdomains('dev.www.example.co.uk', 2) # => ["dev", "www"]
         def extract_subdomains(host, tld_length)
           if named_host?(host)
             extract_subdomains_from(host, tld_length)
@@ -24,6 +36,12 @@ def extract_subdomains(host, tld_length)
           end
         end
 
+        # Returns the subdomains of a host as a String given the domain level.
+        #
+        #    # Top-level domain example
+        #    extract_subdomain('www.example.com', 1) # => "www"
+        #    # Second-level domain example
+        #    extract_subdomain('dev.www.example.co.uk', 2) # => "dev.www"
         def extract_subdomain(host, tld_length)
           extract_subdomains(host, tld_length).join('.')
         end
@@ -173,16 +191,43 @@ def initialize(env)
       end
 
       # Returns the complete URL used for this request.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com'
+      #   req.url # => "http://example.com"
       def url
         protocol + host_with_port + fullpath
       end
 
       # Returns 'https://' if this is an SSL request and 'http://' otherwise.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com'
+      #   req.protocol # => "http://"
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com', 'HTTPS' => 'on'
+      #   req.protocol # => "https://"
       def protocol
         @protocol ||= ssl? ? 'https://' : 'http://'
       end
 
       # Returns the \host for this request, such as "example.com".
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com'
+      #   req.raw_host_with_port # => "example.com"
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.raw_host_with_port # => "example.com:8080"
       def raw_host_with_port
         if forwarded = env["HTTP_X_FORWARDED_HOST"]
           forwarded.split(/,\s?/).last
@@ -192,17 +237,44 @@ def raw_host_with_port
       end
 
       # Returns the host for this request, such as example.com.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.host # => "example.com"
       def host
         raw_host_with_port.sub(/:\d+$/, '')
       end
 
       # Returns a \host:\port string for this request, such as "example.com" or
       # "example.com:8080".
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:80'
+      #   req.host_with_port # => "example.com"
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.host_with_port # => "example.com:8080"
       def host_with_port
         "#{host}#{port_string}"
       end
 
       # Returns the port number of this request as an integer.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com'
+      #   req.port # => 80
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.port # => 8080
       def port
         @port ||= begin
           if raw_host_with_port =~ /:(\d+)$/
@@ -214,6 +286,13 @@ def port
       end
 
       # Returns the standard \port number for this request's protocol.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.standard_port # => 80
       def standard_port
         case protocol
           when 'https://' then 443
@@ -222,18 +301,48 @@ def standard_port
       end
 
       # Returns whether this request is using the standard port
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:80'
+      #   req.standard_port? # => true
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.standard_port? # => false
       def standard_port?
         port == standard_port
       end
 
       # Returns a number \port suffix like 8080 if the \port number of this request
       # is not the default HTTP \port 80 or HTTPS \port 443.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:80'
+      #   req.optional_port # => nil
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.optional_port # => 8080
       def optional_port
         standard_port? ? nil : port
       end
 
       # Returns a string \port suffix, including colon, like ":8080" if the \port
       # number of this request is not the default HTTP \port 80 or HTTPS \port 443.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:80'
+      #   req.port_string # => ""
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.port_string # => ":8080"
       def port_string
         standard_port? ? '' : ":#{port}"
       end

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:

activesupport/lib/active_support/core_ext/module/attribute_accessors.rb

@@ -203,7 +203,7 @@ def #{sym}=(obj)
   #     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)

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

activesupport/lib/active_support/core_ext/numeric/time.rb

@@ -36,33 +36,51 @@ def seconds
   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

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:

activesupport/lib/active_support/core_ext/thread.rb

@@ -67,8 +67,8 @@ def thread_variable?(key)
   #
   #   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

activesupport/lib/active_support/core_ext/time/zones.rb

@@ -51,7 +51,16 @@ def use_zone(time_zone)
       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 @@ def find_zone!(time_zone)
       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

activesupport/lib/active_support/notifications/instrumenter.rb

@@ -57,6 +57,18 @@ def initialize(name, start, ending, transaction_id, payload)
         @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