Improve docs for Rails::Application and add routes_reloader_hook and app_reloader_hooks.

3 files changed, 77 insertions, 29 deletions

diff --git a/railties/lib/rails/application.rb b/railties/lib/rails/application.rb
index f5f47acfbc..f1d546fc59 100644
--- a/railties/lib/rails/application.rb
+++ b/railties/lib/rails/application.rb
@@ -33,6 +33,24 @@ module Rails
   #
   # The Application is also responsible for building the middleware stack.
   #
+  # == Booting process
+  #
+  # The application is also responsible for setting up and executing the booting
+  # process. From the moment you require "config/application.rb" in your app,
+  # the booting process goes like this:
+  #
+  #   1)  require "config/boot.rb" to setup load paths
+  #   2)  require railties and engines
+  #   3)  Define Rails.application as "class MyApp::Application < Rails::Application"
+  #   4)  Run config.before_configuration callbacks
+  #   5)  Load config/environments/ENV.rb
+  #   6)  Run config.before_initialize callbacks
+  #   7)  Run Railtie#initializer defined by railties, engines and application.
+  #       One by one, each engine sets up its load paths, routes and runs its initializer files.
+  #   8)  Build the middleware stack and run to_prepare callbacks
+  #   9)  Run config.before_eager_load and eager_load if cache classes is true
+  #   10) Run config.after_initialize callbacks
+  #
   class Application < Engine
     autoload :Bootstrap,      'rails/application/bootstrap'
     autoload :Configuration,  'rails/application/configuration'
@@ -83,27 +101,55 @@ module Rails
       require environment if environment
     end
 
+    # Reload application routes regardless if they changed or not.
     def reload_routes!
       routes_reloader.reload!
     end
 
-    def routes_reloader
+    def routes_reloader #:nodoc:
       @routes_reloader ||= RoutesReloader.new
     end
 
-    def initialize!(group=:default)
+    # A routes reloader hook that is used to setup to_prepare callbacks.
+    # A plugin may override this if they desire to provide a more
+    # exquisite route reloading.
+    # :api: plugin
+    def routes_reloader_hook
+      app = self
+      lambda { app.routes_reloader.execute_if_updated }
+    end
+
+    # An app reloader hook that is used to setup to_cleanup callbacks.
+    # A plugin may override this if they desire to provide a more exquisite app reloading.
+    # :api: plugin
+    def app_reloader_hook
+      lambda {
+        ActiveSupport::DescendantsTracker.clear
+        ActiveSupport::Dependencies.clear
+      }
+    end
+
+    # Initialize the application passing the given group. By default, the
+    # group is :default but sprockets precompilation passes group equals
+    # to assets if initialize_on_precompile is false to avoid booting the
+    # whole app.
+    def initialize!(group=:default) #:nodoc:
       raise "Application has been already initialized." if @initialized
       run_initializers(group, self)
       @initialized = true
       self
     end
 
+    # Load the application and its railties tasks and invoke the registered hooks.
+    # Check <tt>Rails::Railtie.rake_tasks</tt> for more info.
     def load_tasks(app=self)
       initialize_tasks
       super
       self
     end
 
+    # Load the application console and invoke the registered hooks.
+    # Check <tt>Rails::Railtie.console</tt> for more info.
     def load_console(app=self)
       initialize_console
       super
@@ -129,7 +175,8 @@ module Rails
       })
     end
 
-    def ordered_railties
+    # Returns the ordered railties for this application considering railties_order.
+    def ordered_railties #:nodoc:
       @ordered_railties ||= begin
         order = config.railties_order.map do |railtie|
           if railtie == :main_app
@@ -151,13 +198,13 @@ module Rails
       end
     end
 
-    def initializers
+    def initializers #:nodoc:
       Bootstrap.initializers_for(self) +
       super +
       Finisher.initializers_for(self)
     end
 
-    def config
+    def config #:nodoc:
       @config ||= Application::Configuration.new(find_root_with_flag("config.ru", Dir.pwd))
     end
 
@@ -165,7 +212,7 @@ module Rails
       self
     end
 
-    def helpers_paths
+    def helpers_paths #:nodoc:
       config.helpers_paths
     end
 
@@ -222,7 +269,7 @@ module Rails
       end
     end
 
-    def initialize_tasks
+    def initialize_tasks #:nodoc:
       self.class.rake_tasks do
         require "rails/tasks"
         task :environment do
@@ -232,7 +279,7 @@ module Rails
       end
     end
 
-    def initialize_console
+    def initialize_console #:nodoc:
       require "pp"
       require "rails/console/app"
       require "rails/console/helpers"
diff --git a/railties/lib/rails/application/bootstrap.rb b/railties/lib/rails/application/bootstrap.rb
index 1ae90056d9..e189009cc5 100644
--- a/railties/lib/rails/application/bootstrap.rb
+++ b/railties/lib/rails/application/bootstrap.rb
@@ -59,13 +59,6 @@ module Rails
         end
       end
 
-      initializer :set_clear_dependencies_hook, :group => :all do
-        ActionDispatch::Reloader.to_cleanup do
-          ActiveSupport::DescendantsTracker.clear
-          ActiveSupport::Dependencies.clear
-        end
-      end
-
       # Sets the dependency loading mechanism.
       # TODO: Remove files from the $" and always use require.
       initializer :initialize_dependency_mechanism, :group => :all do
diff --git a/railties/lib/rails/application/finisher.rb b/railties/lib/rails/application/finisher.rb
index fc7d205a6f..df2853498a 100644
--- a/railties/lib/rails/application/finisher.rb
+++ b/railties/lib/rails/application/finisher.rb
@@ -20,12 +20,6 @@ module Rails
         end
       end
 
-      initializer :add_to_prepare_blocks do
-        config.to_prepare_blocks.each do |block|
-          ActionDispatch::Reloader.to_prepare(&block)
-        end
-      end
-
       initializer :add_builtin_route do |app|
         if Rails.env.development?
           app.routes.append do
@@ -38,14 +32,22 @@ module Rails
         build_middleware_stack
       end
 
-      initializer :run_prepare_callbacks do
-        ActionDispatch::Reloader.prepare!
-      end
-
       initializer :define_main_app_helper do |app|
         app.routes.define_mounted_helper(:main_app)
       end
 
+      initializer :add_to_prepare_blocks do
+        config.to_prepare_blocks.each do |block|
+          ActionDispatch::Reloader.to_prepare(&block)
+        end
+      end
+
+      # This needs to happen before eager load so it happens
+      # in exactly the same point regardless of config.cache_classes
+      initializer :run_prepare_callbacks do
+        ActionDispatch::Reloader.prepare!
+      end
+
       initializer :eager_load! do
         if config.cache_classes && !$rails_rake_task
           ActiveSupport.run_load_hooks(:before_eager_load, self)
@@ -53,15 +55,21 @@ module Rails
         end
       end
 
+      # All initialization is done, including eager loading in production
       initializer :finisher_hook do
         ActiveSupport.run_load_hooks(:after_initialize, self)
       end
 
-      # Force routes to be loaded just at the end and add it to to_prepare callbacks
-      # This needs to be after the finisher hook to ensure routes added in the hook
-      # are still loaded.
+      # Set app reload just after the finisher hook to ensure
+      # paths added in the hook are still loaded.
+      initializer :set_clear_dependencies_hook, :group => :all do |app|
+        ActionDispatch::Reloader.to_cleanup(&app.app_reloader_hook)
+      end
+
+      # Set app reload just after the finisher hook to ensure
+      # routes added in the hook are still loaded.
       initializer :set_routes_reloader do |app|
-        reloader = lambda { app.routes_reloader.execute_if_updated }
+        reloader = app.routes_reloader_hook
         reloader.call
         ActionDispatch::Reloader.to_prepare(&reloader)
       end