activesupport 6.0.6.1 → 7.1.3.2

data/lib/active_support/inflector/methods.rb

@@ -3,12 +3,14 @@
 require "active_support/inflections"
 
 module ActiveSupport
+  # = Active Support \Inflector
+  #
   # The Inflector transforms words from singular to plural, class names to table
   # names, modularized class names to ones without, and class names to foreign
   # keys. The default inflections for pluralization, singularization, and
   # uncountable words are kept in inflections.rb.
   #
-  # The Rails core team has stated patches for the inflections library will not
+  # The \Rails core team has stated patches for the inflections library will not
   # be accepted in order to avoid breaking legacy applications which may be
   # relying on errant inflections. If you discover an incorrect inflection and
   # require it for your application or wish to define rules for languages other
@@ -67,13 +69,19 @@ module ActiveSupport
     #   camelize(underscore('SSLError'))        # => "SslError"
     def camelize(term, uppercase_first_letter = true)
       string = term.to_s
-      if uppercase_first_letter
-        string = string.sub(/^[a-z\d]*/) { |match| inflections.acronyms[match] || match.capitalize }
+      # String#camelize takes a symbol (:upper or :lower), so here we also support :lower to keep the methods consistent.
+      if !uppercase_first_letter || uppercase_first_letter == :lower
+        string = string.sub(inflections.acronyms_camelize_regex) { |match| match.downcase! || match }
+      elsif string.match?(/\A[a-z\d]*\z/)
+        return inflections.acronyms[string]&.dup || string.capitalize
       else
-        string = string.sub(inflections.acronyms_camelize_regex) { |match| match.downcase }
+        string = string.sub(/^[a-z\d]*/) { |match| inflections.acronyms[match] || match.capitalize! || match }
+      end
+      string.gsub!(/(?:_|(\/))([a-z\d]*)/i) do
+        word = $2
+        substituted = inflections.acronyms[word] || word.capitalize! || word
+        $1 ? "::#{substituted}" : substituted
       end
-      string.gsub!(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{inflections.acronyms[$2] || $2.capitalize}" }
-      string.gsub!("/", "::")
       string
     end
 
@@ -89,11 +97,10 @@ module ActiveSupport
     #
     #   camelize(underscore('SSLError'))  # => "SslError"
     def underscore(camel_cased_word)
-      return camel_cased_word unless /[A-Z-]|::/.match?(camel_cased_word)
+      return camel_cased_word.to_s.dup unless /[A-Z-]|::/.match?(camel_cased_word)
       word = camel_cased_word.to_s.gsub("::", "/")
       word.gsub!(inflections.acronyms_underscore_regex) { "#{$1 && '_' }#{$2.downcase}" }
-      word.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
-      word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+      word.gsub!(/(?<=[A-Z])(?=[A-Z][a-z])|(?<=[a-z\d])(?=[A-Z])/, "_")
       word.tr!("-", "_")
       word.downcase!
       word
@@ -105,7 +112,7 @@ module ActiveSupport
     #
     # * Applies human inflection rules to the argument.
     # * Deletes leading underscores, if any.
-    # * Removes a "_id" suffix if present.
+    # * Removes an "_id" suffix if present.
     # * Replaces underscores with spaces, if any.
     # * Downcases all words except acronyms.
     # * Capitalizes the first word.
@@ -119,7 +126,7 @@ module ActiveSupport
     #   humanize('author_id')                        # => "Author"
     #   humanize('author_id', capitalize: false)     # => "author"
     #   humanize('_id')                              # => "Id"
-    #   humanize('author_id', keep_id_suffix: true)  # => "Author Id"
+    #   humanize('author_id', keep_id_suffix: true)  # => "Author id"
     #
     # If "SSL" was defined to be an acronym:
     #
@@ -130,54 +137,65 @@ module ActiveSupport
 
       inflections.humans.each { |(rule, replacement)| break if result.sub!(rule, replacement) }
 
-      result.sub!(/\A_+/, "")
-      unless keep_id_suffix
-        result.sub!(/_id\z/, "")
-      end
       result.tr!("_", " ")
+      result.lstrip!
+      if !keep_id_suffix && lower_case_and_underscored_word&.end_with?("_id")
+        result.delete_suffix!(" id")
+      end
 
-      result.gsub!(/([a-z\d]*)/i) do |match|
-        "#{inflections.acronyms[match.downcase] || match.downcase}"
+      result.gsub!(/([a-z\d]+)/i) do |match|
+        match.downcase!
+        inflections.acronyms[match] || match
       end
 
       if capitalize
-        result.sub!(/\A\w/) { |match| match.upcase }
+        result.sub!(/\A\w/) do |match|
+          match.upcase!
+          match
+        end
       end
 
       result
     end
 
-    # Converts just the first character to uppercase.
+    # Converts the first character in the string to uppercase.
     #
     #   upcase_first('what a Lovely Day') # => "What a Lovely Day"
     #   upcase_first('w')                 # => "W"
     #   upcase_first('')                  # => ""
     def upcase_first(string)
-      string.length > 0 ? string[0].upcase.concat(string[1..-1]) : ""
+      string.length > 0 ? string[0].upcase.concat(string[1..-1]) : +""
+    end
+
+    # Converts the first character in the string to lowercase.
+    #
+    #   downcase_first('If they enjoyed The Matrix') # => "if they enjoyed The Matrix"
+    #   downcase_first('I')                          # => "i"
+    #   downcase_first('')                           # => ""
+    def downcase_first(string)
+      string.length > 0 ? string[0].downcase.concat(string[1..-1]) : +""
     end
 
     # Capitalizes all the words and replaces some characters in the string to
     # create a nicer looking title. +titleize+ is meant for creating pretty
-    # output. It is not used in the Rails internals.
+    # output. It is not used in the \Rails internals.
     #
     # The trailing '_id','Id'.. can be kept and capitalized by setting the
     # optional parameter +keep_id_suffix+ to true.
     # By default, this parameter is false.
     #
-    # +titleize+ is also aliased as +titlecase+.
-    #
     #   titleize('man from the boondocks')                       # => "Man From The Boondocks"
     #   titleize('x-men: the last stand')                        # => "X Men: The Last Stand"
     #   titleize('TheManWithoutAPast')                           # => "The Man Without A Past"
     #   titleize('raiders_of_the_lost_ark')                      # => "Raiders Of The Lost Ark"
     #   titleize('string_ending_with_id', keep_id_suffix: true)  # => "String Ending With Id"
     def titleize(word, keep_id_suffix: false)
-      humanize(underscore(word), keep_id_suffix: keep_id_suffix).gsub(/\b(?<!\w['’`])[a-z]/) do |match|
+      humanize(underscore(word), keep_id_suffix: keep_id_suffix).gsub(/\b(?<!\w['’`()])[a-z]/) do |match|
         match.capitalize
       end
     end
 
-    # Creates the name of a table like Rails does for models to table names.
+    # Creates the name of a table like \Rails does for models to table names.
     # This method uses the #pluralize method on the last word in the string.
     #
     #   tableize('RawScaledScorer') # => "raw_scaled_scorers"
@@ -187,9 +205,9 @@ module ActiveSupport
       pluralize(underscore(class_name))
     end
 
-    # Creates a class name from a plural table name like Rails does for table
-    # names to models. Note that this returns a string and not a Class (To
-    # convert to an actual class follow +classify+ with #constantize).
+    # Creates a class name from a plural table name like \Rails does for table
+    # names to models. Note that this returns a string and not a Class. (To
+    # convert to an actual class follow +classify+ with #constantize.)
     #
     #   classify('ham_and_eggs') # => "HamAndEgg"
     #   classify('posts')        # => "Post"
@@ -220,7 +238,7 @@ module ActiveSupport
     def demodulize(path)
       path = path.to_s
       if i = path.rindex("::")
-        path[(i + 2)..-1]
+        path[(i + 2), path.length]
       else
         path
       end
@@ -269,34 +287,7 @@ module ActiveSupport
     # NameError is raised when the name is not in CamelCase or the constant is
     # unknown.
     def constantize(camel_cased_word)
-      names = camel_cased_word.split("::")
-
-      # Trigger a built-in NameError exception including the ill-formed constant in the message.
-      Object.const_get(camel_cased_word) if names.empty?
-
-      # Remove the first blank element in case of '::ClassName' notation.
-      names.shift if names.size > 1 && names.first.empty?
-
-      names.inject(Object) do |constant, name|
-        if constant == Object
-          constant.const_get(name)
-        else
-          candidate = constant.const_get(name)
-          next candidate if constant.const_defined?(name, false)
-          next candidate unless Object.const_defined?(name)
-
-          # Go down the ancestors to check if it is owned directly. The check
-          # stops when we reach Object or the end of ancestors tree.
-          constant = constant.ancestors.inject(constant) do |const, ancestor|
-            break const    if ancestor == Object
-            break ancestor if ancestor.const_defined?(name, false)
-            const
-          end
-
-          # owner is in Object, so raise
-          constant.const_get(name, false)
-        end
-      end
+      Object.const_get(camel_cased_word)
     end
 
     # Tries to find a constant with the name specified in the argument string.
@@ -326,10 +317,9 @@ module ActiveSupport
     rescue NameError => e
       raise if e.name && !(camel_cased_word.to_s.split("::").include?(e.name.to_s) ||
         e.name.to_s == camel_cased_word.to_s)
-    rescue ArgumentError => e
-      raise unless /not missing constant #{const_regexp(camel_cased_word)}!$/.match?(e.message)
     rescue LoadError => e
-      raise unless /Unable to autoload constant #{const_regexp(camel_cased_word)}/.match?(e.message)
+      message = e.respond_to?(:original_message) ? e.original_message : e.message
+      raise unless /Unable to autoload constant #{const_regexp(camel_cased_word)}/.match?(message)
     end
 
     # Returns the suffix that should be added to a number to denote the position
@@ -367,11 +357,11 @@ module ActiveSupport
       def const_regexp(camel_cased_word)
         parts = camel_cased_word.split("::")
 
-        return Regexp.escape(camel_cased_word) if parts.blank?
+        return Regexp.escape(camel_cased_word) if parts.empty?
 
         last = parts.pop
 
-        parts.reverse.inject(last) do |acc, part|
+        parts.reverse!.inject(last) do |acc, part|
           part.empty? ? acc : "#{part}(::#{acc})?"
         end
       end
@@ -381,8 +371,8 @@ module ActiveSupport
       # If passed an optional +locale+ parameter, the uncountables will be
       # found for that locale.
       #
-      #  apply_inflections('post', inflections.plurals, :en)    # => "posts"
-      #  apply_inflections('posts', inflections.singulars, :en) # => "post"
+      #   apply_inflections('post', inflections.plurals, :en)    # => "posts"
+      #   apply_inflections('posts', inflections.singulars, :en) # => "post"
       def apply_inflections(word, rules, locale = :en)
         result = word.to_s.dup
 

data/lib/active_support/inflector/transliterate.rb

@@ -5,6 +5,8 @@ require "active_support/i18n"
 
 module ActiveSupport
   module Inflector
+    ALLOWED_ENCODINGS_FOR_TRANSLITERATE = [Encoding::UTF_8, Encoding::US_ASCII, Encoding::GB18030].freeze
+
     # Replaces non-ASCII characters with an ASCII approximation, or if none
     # exists, a replacement character which defaults to "?".
     #
@@ -57,14 +59,14 @@ module ActiveSupport
     #   transliterate('Jürgen', locale: :de)
     #   # => "Juergen"
     #
-    # Transliteration is restricted to UTF-8, US-ASCII and GB18030 strings
+    # Transliteration is restricted to UTF-8, US-ASCII, and GB18030 strings.
     # Other encodings will raise an ArgumentError.
     def transliterate(string, replacement = "?", locale: nil)
-      string = string.dup if string.frozen?
       raise ArgumentError, "Can only transliterate strings. Received #{string.class.name}" unless string.is_a?(String)
+      raise ArgumentError, "Cannot transliterate strings with #{string.encoding} encoding" unless ALLOWED_ENCODINGS_FOR_TRANSLITERATE.include?(string.encoding)
 
-      allowed_encodings = [Encoding::UTF_8, Encoding::US_ASCII, Encoding::GB18030]
-      raise ArgumentError, "Can not transliterate strings with #{string.encoding} encoding" unless allowed_encodings.include?(string.encoding)
+      return string.dup if string.ascii_only?
+      string = string.dup if string.frozen?
 
       input_encoding = string.encoding
 
@@ -117,7 +119,7 @@ module ActiveSupport
     # If the optional parameter +locale+ is specified,
     # the word will be parameterized as a word of that language.
     # By default, this parameter is set to <tt>nil</tt> and it will use
-    # the configured <tt>I18n.locale<tt>.
+    # the configured <tt>I18n.locale</tt>.
     def parameterize(string, separator: "-", preserve_case: false, locale: nil)
       # Replace accented chars with their ASCII equivalents.
       parameterized_string = transliterate(string, locale: locale)

data/lib/active_support/isolated_execution_state.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "fiber"
+
+module ActiveSupport
+  module IsolatedExecutionState # :nodoc:
+    @isolation_level = nil
+
+    Thread.attr_accessor :active_support_execution_state
+    Fiber.attr_accessor :active_support_execution_state
+
+    class << self
+      attr_reader :isolation_level, :scope
+
+      def isolation_level=(level)
+        return if level == @isolation_level
+
+        unless %i(thread fiber).include?(level)
+          raise ArgumentError, "isolation_level must be `:thread` or `:fiber`, got: `#{level.inspect}`"
+        end
+
+        clear if @isolation_level
+
+        @scope =
+          case level
+          when :thread; Thread
+          when :fiber; Fiber
+          end
+
+        @isolation_level = level
+      end
+
+      def unique_id
+        self[:__id__] ||= Object.new
+      end
+
+      def [](key)
+        state[key]
+      end
+
+      def []=(key, value)
+        state[key] = value
+      end
+
+      def key?(key)
+        state.key?(key)
+      end
+
+      def delete(key)
+        state.delete(key)
+      end
+
+      def clear
+        state.clear
+      end
+
+      def context
+        scope.current
+      end
+
+      def share_with(other)
+        # Action Controller streaming spawns a new thread and copy thread locals.
+        # We do the same here for backward compatibility, but this is very much a hack
+        # and streaming should be rethought.
+        context.active_support_execution_state = other.active_support_execution_state.dup
+      end
+
+      private
+        def state
+          context.active_support_execution_state ||= {}
+        end
+    end
+
+    self.isolation_level = :thread
+  end
+end

data/lib/active_support/json/decoding.rb

@@ -5,13 +5,13 @@ require "active_support/core_ext/module/delegation"
 require "json"
 
 module ActiveSupport
-  # Look for and parse json strings that look like ISO 8601 times.
+  # Look for and parse JSON strings that look like ISO 8601 times.
   mattr_accessor :parse_json_times
 
   module JSON
     # matches YAML-formatted dates
-    DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/
-    DATETIME_REGEX = /^(?:\d{4}-\d{2}-\d{2}|\d{4}-\d{1,2}-\d{1,2}[T \t]+\d{1,2}:\d{2}:\d{2}(\.[0-9]*)?(([ \t]*)Z|[-+]\d{2}?(:\d{2})?)?)$/
+    DATE_REGEX = /\A\d{4}-\d{2}-\d{2}\z/
+    DATETIME_REGEX = /\A(?:\d{4}-\d{2}-\d{2}|\d{4}-\d{1,2}-\d{1,2}[T \t]+\d{1,2}:\d{2}:\d{2}(\.[0-9]*)?(([ \t]*)Z|[-+]\d{2}?(:\d{2})?)?)\z/
 
     class << self
       # Parses a JSON string (JavaScript Object Notation) into a hash.
@@ -28,6 +28,7 @@ module ActiveSupport
           data
         end
       end
+      alias_method :load, :decode
 
       # Returns the class of the error that will be raised when there is an
       # error in decoding JSON. Using this method means you won't directly
@@ -63,8 +64,8 @@ module ActiveSupport
           when Array
             data.map! { |d| convert_dates_from(d) }
           when Hash
-            data.each do |key, value|
-              data[key] = convert_dates_from(value)
+            data.transform_values! do |value|
+              convert_dates_from(value)
             end
           else
             data

data/lib/active_support/json/encoding.rb

@@ -18,12 +18,15 @@ module ActiveSupport
     #
     #   ActiveSupport::JSON.encode({ team: 'rails', players: '36' })
     #   # => "{\"team\":\"rails\",\"players\":\"36\"}"
-    def self.encode(value, options = nil)
-      Encoding.json_encoder.new(options).encode(value)
+    class << self
+      def encode(value, options = nil)
+        Encoding.json_encoder.new(options).encode(value)
+      end
+      alias_method :dump, :encode
     end
 
-    module Encoding #:nodoc:
-      class JSONGemEncoder #:nodoc:
+    module Encoding # :nodoc:
+      class JSONGemEncoder # :nodoc:
         attr_reader :options
 
         def initialize(options = nil)
@@ -32,49 +35,27 @@ module ActiveSupport
 
         # Encode the given object into a JSON string
         def encode(value)
-          stringify jsonify value.as_json(options.dup)
-        end
+          unless options.empty?
+            value = value.as_json(options.dup)
+          end
+          json = stringify(jsonify(value))
 
-        private
           # Rails does more escaping than the JSON gem natively does (we
           # escape \u2028 and \u2029 and optionally >, <, & to work around
           # certain browser problems).
-          ESCAPED_CHARS = {
-            "\u2028" => '\u2028',
-            "\u2029" => '\u2029',
-            ">"      => '\u003e',
-            "<"      => '\u003c',
-            "&"      => '\u0026',
-            }
-
-          ESCAPE_REGEX_WITH_HTML_ENTITIES = /[\u2028\u2029><&]/u
-          ESCAPE_REGEX_WITHOUT_HTML_ENTITIES = /[\u2028\u2029]/u
-
-          # This class wraps all the strings we see and does the extra escaping
-          class EscapedString < String #:nodoc:
-            def to_json(*)
-              if Encoding.escape_html_entities_in_json
-                s = super
-                s.gsub! ESCAPE_REGEX_WITH_HTML_ENTITIES, ESCAPED_CHARS
-                s
-              else
-                s = super
-                s.gsub! ESCAPE_REGEX_WITHOUT_HTML_ENTITIES, ESCAPED_CHARS
-                s
-              end
-            end
-
-            def to_s
-              self
-            end
+          if Encoding.escape_html_entities_in_json
+            json.gsub!(">", '\u003e')
+            json.gsub!("<", '\u003c')
+            json.gsub!("&", '\u0026')
           end
+          json.gsub!("\u2028", '\u2028')
+          json.gsub!("\u2029", '\u2029')
+          json
+        end
 
-          # Mark these as private so we don't leak encoding-specific constructs
-          private_constant :ESCAPED_CHARS, :ESCAPE_REGEX_WITH_HTML_ENTITIES,
-            :ESCAPE_REGEX_WITHOUT_HTML_ENTITIES, :EscapedString
-
+        private
           # Convert an object into a "JSON-ready" representation composed of
-          # primitives like Hash, Array, String, Numeric,
+          # primitives like Hash, Array, String, Symbol, Numeric,
           # and +true+/+false+/+nil+.
           # Recursively calls #as_json to the object to recursively build a
           # fully JSON-ready object.
@@ -88,12 +69,17 @@ module ActiveSupport
           # calls.
           def jsonify(value)
             case value
-            when String
-              EscapedString.new(value)
-            when Numeric, NilClass, TrueClass, FalseClass
+            when String, Integer, Symbol, nil, true, false
+              value
+            when Numeric
               value.as_json
             when Hash
-              Hash[value.map { |k, v| [jsonify(k), jsonify(v)] }]
+              result = {}
+              value.each do |k, v|
+                k = k.to_s unless String === k
+                result[k] = jsonify(v)
+              end
+              result
             when Array
               value.map { |v| jsonify(v) }
             else
@@ -120,7 +106,7 @@ module ActiveSupport
         # Defaults to 3 (equivalent to millisecond precision)
         attr_accessor :time_precision
 
-        # Sets the encoder used by Rails to encode Ruby objects into JSON strings
+        # Sets the encoder used by \Rails to encode Ruby objects into JSON strings
         # in +Object#to_json+ and +ActiveSupport::JSON.encode+.
         attr_accessor :json_encoder
       end

data/lib/active_support/key_generator.rb

@@ -4,29 +4,54 @@ require "concurrent/map"
 require "openssl"
 
 module ActiveSupport
+  # = Key Generator
+  #
   # KeyGenerator is a simple wrapper around OpenSSL's implementation of PBKDF2.
   # It can be used to derive a number of keys for various purposes from a given secret.
-  # This lets Rails applications have a single secure secret, but avoid reusing that
+  # This lets \Rails applications have a single secure secret, but avoid reusing that
   # key in multiple incompatible contexts.
   class KeyGenerator
+    class << self
+      def hash_digest_class=(klass)
+        if klass.kind_of?(Class) && klass < OpenSSL::Digest
+          @hash_digest_class = klass
+        else
+          raise ArgumentError, "#{klass} is expected to be an OpenSSL::Digest subclass"
+        end
+      end
+
+      def hash_digest_class
+        @hash_digest_class ||= OpenSSL::Digest::SHA1
+      end
+    end
+
     def initialize(secret, options = {})
       @secret = secret
       # The default iterations are higher than required for our key derivation uses
       # on the off chance someone uses this for password storage
       @iterations = options[:iterations] || 2**16
+      # Also allow configuration here so people can use this to build a rotation
+      # scheme when switching the digest class.
+      @hash_digest_class = options[:hash_digest_class] || self.class.hash_digest_class
     end
 
-    # Returns a derived key suitable for use.  The default key_size is chosen
+    # Returns a derived key suitable for use.  The default +key_size+ is chosen
     # to be compatible with the default settings of ActiveSupport::MessageVerifier.
-    # i.e. OpenSSL::Digest::SHA1#block_length
+    # i.e. <tt>OpenSSL::Digest::SHA1#block_length</tt>
     def generate_key(salt, key_size = 64)
-      OpenSSL::PKCS5.pbkdf2_hmac_sha1(@secret, salt, @iterations, key_size)
+      OpenSSL::PKCS5.pbkdf2_hmac(@secret, salt, @iterations, key_size, @hash_digest_class.new)
+    end
+
+    def inspect # :nodoc:
+      "#<#{self.class.name}:#{'%#016x' % (object_id << 1)}>"
     end
   end
 
+  # = Caching Key Generator
+  #
   # CachingKeyGenerator is a wrapper around KeyGenerator which allows users to avoid
-  # re-executing the key generation process when it's called using the same salt and
-  # key_size.
+  # re-executing the key generation process when it's called using the same +salt+ and
+  # +key_size+.
   class CachingKeyGenerator
     def initialize(key_generator)
       @key_generator = key_generator
@@ -35,7 +60,7 @@ module ActiveSupport
 
     # Returns a derived key suitable for use.
     def generate_key(*args)
-      @cache_keys[args.join] ||= @key_generator.generate_key(*args)
+      @cache_keys[args.join("|")] ||= @key_generator.generate_key(*args)
     end
   end
 end

data/lib/active_support/lazy_load_hooks.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
 module ActiveSupport
-  # lazy_load_hooks allows Rails to lazily load a lot of components and thus
+  # = Lazy Load Hooks
+  #
+  # LazyLoadHooks allows \Rails to lazily load a lot of components and thus
   # making the app boot faster. Because of this feature now there is no need to
-  # require <tt>ActiveRecord::Base</tt> at boot time purely to apply
+  # require +ActiveRecord::Base+ at boot time purely to apply
   # configuration. Instead a hook is registered that applies configuration once
-  # <tt>ActiveRecord::Base</tt> is loaded. Here <tt>ActiveRecord::Base</tt> is
+  # +ActiveRecord::Base+ is loaded. Here +ActiveRecord::Base+ is
   # used as example but this feature can be applied elsewhere too.
   #
-  # Here is an example where +on_load+ method is called to register a hook.
+  # Here is an example where on_load method is called to register a hook.
   #
   #   initializer 'active_record.initialize_timezone' do
   #     ActiveSupport.on_load(:active_record) do
@@ -18,10 +20,26 @@ module ActiveSupport
   #   end
   #
   # When the entirety of +ActiveRecord::Base+ has been
-  # evaluated then +run_load_hooks+ is invoked. The very last line of
+  # evaluated then run_load_hooks is invoked. The very last line of
   # +ActiveRecord::Base+ is:
   #
   #   ActiveSupport.run_load_hooks(:active_record, ActiveRecord::Base)
+  #
+  # run_load_hooks will then execute all the hooks that were registered
+  # with the on_load method. In the case of the above example, it will
+  # execute the block of code that is in the +initializer+.
+  #
+  # Registering a hook that has already run results in that hook executing
+  # immediately. This allows hooks to be nested for code that relies on
+  # multiple lazily loaded components:
+  #
+  #   initializer "action_text.renderer" do
+  #     ActiveSupport.on_load(:action_controller_base) do
+  #       ActiveSupport.on_load(:action_text_content) do
+  #         self.default_renderer = Class.new(ActionController::Base).renderer
+  #       end
+  #     end
+  #   end
   module LazyLoadHooks
     def self.extended(base) # :nodoc:
       base.class_eval do
@@ -31,8 +49,9 @@ module ActiveSupport
       end
     end
 
-    # Declares a block that will be executed when a Rails component is fully
-    # loaded.
+    # Declares a block that will be executed when a \Rails component is fully
+    # loaded. If the component has already loaded, the block is executed
+    # immediately.
     #
     # Options:
     #
@@ -46,6 +65,13 @@ module ActiveSupport
       @load_hooks[name] << [block, options]
     end
 
+    # Executes all blocks registered to +name+ via on_load, using +base+ as the
+    # evaluation context.
+    #
+    #   ActiveSupport.run_load_hooks(:active_record, ActiveRecord::Base)
+    #
+    # In the case of the above example, it will execute all hooks registered
+    # for +:active_record+ within the class +ActiveRecord::Base+.
     def run_load_hooks(name, base = Object)
       @loaded[name] << base
       @load_hooks[name].each do |hook, options|