1 files changed, 91 insertions, 81 deletions

diff --git a/railties/lib/rails/railtie.rb b/railties/lib/rails/railtie.rb
index 8c24d1d56d..a67b90e285 100644
--- a/railties/lib/rails/railtie.rb
+++ b/railties/lib/rails/railtie.rb
@@ -1,38 +1,39 @@
-require 'rails/initializable'
-require 'rails/configuration'
-require 'active_support/inflector'
-require 'active_support/core_ext/module/introspection'
-require 'active_support/core_ext/module/delegation'
+# frozen_string_literal: true
+
+require "rails/initializable"
+require "active_support/inflector"
+require "active_support/core_ext/module/introspection"
+require "active_support/core_ext/module/delegation"
 
 module Rails
-  # Railtie is the core of the Rails framework and provides several hooks to extend
-  # Rails and/or modify the initialization process.
+  # <tt>Rails::Railtie</tt> is the core of the Rails framework and provides
+  # several hooks to extend Rails and/or modify the initialization process.
   #
-  # Every major component of Rails (Action Mailer, Action Controller,
-  # Action View and Active Record) is a Railtie. Each of
-  # them is responsible for their own initialization. This makes Rails itself
-  # absent of any component hooks, allowing other components to be used in
-  # place of any of the Rails defaults.
+  # Every major component of Rails (Action Mailer, Action Controller, Active
+  # Record, etc.) implements a railtie. Each of them is responsible for their
+  # own initialization. This makes Rails itself absent of any component hooks,
+  # allowing other components to be used in place of any of the Rails defaults.
   #
-  # Developing a Rails extension does _not_ require any implementation of
-  # Railtie, but if you need to interact with the Rails framework during
-  # or after boot, then Railtie is needed.
+  # Developing a Rails extension does _not_ require implementing a railtie, but
+  # if you need to interact with the Rails framework during or after boot, then
+  # a railtie is needed.
   #
-  # For example, an extension doing any of the following would require Railtie:
+  # For example, an extension doing any of the following would need a railtie:
   #
   # * creating initializers
   # * configuring a Rails framework for the application, like setting a generator
   # * adding <tt>config.*</tt> keys to the environment
-  # * setting up a subscriber with ActiveSupport::Notifications
-  # * adding rake tasks
+  # * setting up a subscriber with <tt>ActiveSupport::Notifications</tt>
+  # * adding Rake tasks
   #
-  # == Creating your Railtie
+  # == Creating a Railtie
   #
-  # To extend Rails using Railtie, create a Railtie class which inherits
-  # from Rails::Railtie within your extension's namespace. This class must be
-  # loaded during the Rails boot process.
+  # To extend Rails using a railtie, create a subclass of <tt>Rails::Railtie</tt>.
+  # This class must be loaded during the Rails boot process, and is conventionally
+  # called <tt>MyNamespace::Railtie</tt>.
   #
-  # The following example demonstrates an extension which can be used with or without Rails.
+  # The following example demonstrates an extension which can be used with or
+  # without Rails.
   #
   #   # lib/my_gem/railtie.rb
   #   module MyGem
@@ -45,8 +46,8 @@ module Rails
   #
   # == Initializers
   #
-  # To add an initialization step from your Railtie to Rails boot process, you just need
-  # to create an initializer block:
+  # To add an initialization step to the Rails boot process from your railtie, just
+  # define the initialization code with the +initializer+ macro:
   #
   #   class MyRailtie < Rails::Railtie
   #     initializer "my_railtie.configure_rails_initialization" do
@@ -55,7 +56,7 @@ module Rails
   #   end
   #
   # If specified, the block can also receive the application object, in case you
-  # need to access some application specific configuration, like middleware:
+  # need to access some application-specific configuration, like middleware:
   #
   #   class MyRailtie < Rails::Railtie
   #     initializer "my_railtie.configure_rails_initialization" do |app|
@@ -63,54 +64,57 @@ module Rails
   #     end
   #   end
   #
-  # Finally, you can also pass <tt>:before</tt> and <tt>:after</tt> as option to initializer,
-  # in case you want to couple it with a specific step in the initialization process.
+  # Finally, you can also pass <tt>:before</tt> and <tt>:after</tt> as options to
+  # +initializer+, in case you want to couple it with a specific step in the
+  # initialization process.
   #
   # == Configuration
   #
-  # Inside the Railtie class, you can access a config object which contains configuration
-  # shared by all railties and the application:
+  # Railties can access a config object which contains configuration shared by all
+  # railties and the application:
   #
   #   class MyRailtie < Rails::Railtie
   #     # Customize the ORM
   #     config.app_generators.orm :my_railtie_orm
   #
   #     # Add a to_prepare block which is executed once in production
-  #     # and before each request in development
+  #     # and before each request in development.
   #     config.to_prepare do
   #       MyRailtie.setup!
   #     end
   #   end
   #
-  # == Loading rake tasks and generators
+  # == Loading Rake Tasks and Generators
   #
-  # If your railtie has rake tasks, you can tell Rails to load them through the method
-  # rake_tasks:
+  # If your railtie has Rake tasks, you can tell Rails to load them through the method
+  # +rake_tasks+:
   #
   #   class MyRailtie < Rails::Railtie
   #     rake_tasks do
-  #       load "path/to/my_railtie.tasks"
+  #       load 'path/to/my_railtie.tasks'
   #     end
   #   end
   #
   # By default, Rails loads generators from your load path. However, if you want to place
-  # your generators at a different location, you can specify in your Railtie a block which
+  # your generators at a different location, you can specify in your railtie a block which
   # will load them during normal generators lookup:
   #
   #   class MyRailtie < Rails::Railtie
   #     generators do
-  #       require "path/to/my_railtie_generator"
+  #       require 'path/to/my_railtie_generator'
   #     end
   #   end
   #
+  # Since filenames on the load path are shared across gems, be sure that files you load
+  # through a railtie have unique names.
+  #
   # == Application and Engine
   #
-  # A Rails::Engine is nothing more than a Railtie with some initializers already set.
-  # And since Rails::Application is an engine, the same configuration described here
-  # can be used in both.
+  # An engine is nothing more than a railtie with some initializers already set. And since
+  # <tt>Rails::Application</tt> is an engine, the same configuration described here can be
+  # used in both.
   #
   # Be sure to look at the documentation of those specific classes for more information.
-  #
   class Railtie
     autoload :Configuration, "rails/railtie/configuration"
 
@@ -133,27 +137,19 @@ module Rails
       end
 
       def rake_tasks(&blk)
-        @rake_tasks ||= []
-        @rake_tasks << blk if blk
-        @rake_tasks
+        register_block_for(:rake_tasks, &blk)
       end
 
       def console(&blk)
-        @load_console ||= []
-        @load_console << blk if blk
-        @load_console
+        register_block_for(:load_console, &blk)
       end
 
       def runner(&blk)
-        @load_runner ||= []
-        @load_runner << blk if blk
-        @load_runner
+        register_block_for(:runner, &blk)
       end
 
       def generators(&blk)
-        @generators ||= []
-        @generators << blk if blk
-        @generators
+        register_block_for(:generators, &blk)
       end
 
       def abstract_railtie?
@@ -171,10 +167,6 @@ module Rails
         @instance ||= new
       end
 
-      def respond_to_missing?(*args)
-        instance.respond_to?(*args) || super
-      end
-
       # Allows you to configure the railtie. This is the same method seen in
       # Railtie::Configurable, but this module is no longer required for all
       # subclasses of Railtie so we provide the class method here.
@@ -182,11 +174,15 @@ module Rails
         instance.configure(&block)
       end
 
-      protected
+      private
         def generate_railtie_name(string)
           ActiveSupport::Inflector.underscore(string).tr("/", "_")
         end
 
+        def respond_to_missing?(name, _)
+          instance.respond_to?(name) || super
+        end
+
         # If the class method does not have a method, then send the method call
         # to the Railtie instance.
         def method_missing(name, *args, &block)
@@ -196,55 +192,69 @@ module Rails
             super
           end
         end
+
+        # receives an instance variable identifier, set the variable value if is
+        # blank and append given block to value, which will be used later in
+        # `#each_registered_block(type, &block)`
+        def register_block_for(type, &blk)
+          var_name = "@#{type}"
+          blocks = instance_variable_defined?(var_name) ? instance_variable_get(var_name) : instance_variable_set(var_name, [])
+          blocks << blk if blk
+          blocks
+        end
     end
 
     delegate :railtie_name, to: :class
 
-    def initialize
+    def initialize #:nodoc:
       if self.class.abstract_railtie?
         raise "#{self.class.name} is abstract, you cannot instantiate it directly."
       end
     end
 
-    def configure(&block)
+    def configure(&block) #:nodoc:
       instance_eval(&block)
     end
 
+    # This is used to create the <tt>config</tt> object on Railties, an instance of
+    # Railtie::Configuration, that is used by Railties and Application to store
+    # related configuration.
     def config
       @config ||= Railtie::Configuration.new
     end
 
-    def railtie_namespace
-      @railtie_namespace ||= self.class.parents.detect { |n| n.respond_to?(:railtie_namespace) }
+    def railtie_namespace #:nodoc:
+      @railtie_namespace ||= self.class.module_parents.detect { |n| n.respond_to?(:railtie_namespace) }
     end
 
     protected
 
-    def run_console_blocks(app) #:nodoc:
-      each_registered_block(:console) { |block| block.call(app) }
-    end
+      def run_console_blocks(app) #:nodoc:
+        each_registered_block(:console) { |block| block.call(app) }
+      end
 
-    def run_generators_blocks(app) #:nodoc:
-      each_registered_block(:generators) { |block| block.call(app) }
-    end
+      def run_generators_blocks(app) #:nodoc:
+        each_registered_block(:generators) { |block| block.call(app) }
+      end
 
-    def run_runner_blocks(app) #:nodoc:
-      each_registered_block(:runner) { |block| block.call(app) }
-    end
+      def run_runner_blocks(app) #:nodoc:
+        each_registered_block(:runner) { |block| block.call(app) }
+      end
 
-    def run_tasks_blocks(app) #:nodoc:
-      extend Rake::DSL
-      each_registered_block(:rake_tasks) { |block| instance_exec(app, &block) }
-    end
+      def run_tasks_blocks(app) #:nodoc:
+        extend Rake::DSL
+        each_registered_block(:rake_tasks) { |block| instance_exec(app, &block) }
+      end
 
     private
 
-    def each_registered_block(type, &block)
-      klass = self.class
-      while klass.respond_to?(type)
-        klass.public_send(type).each(&block)
-        klass = klass.superclass
+      # run `&block` in every registered block in `#register_block_for`
+      def each_registered_block(type, &block)
+        klass = self.class
+        while klass.respond_to?(type)
+          klass.public_send(type).each(&block)
+          klass = klass.superclass
+        end
       end
-    end
   end
 end