edit pass over the RDoc of Rails::Railtie [ci skip]

The pass touches a few minor things.

One important aspect is that the wording treats "railtie" as a
regular noun. This is so because Railtie is a constant and
generally the text refers to "classes that act as railties",
which is different.

Railties are so fundamental in Rails that deserve a noun,
like engine, class, array, application, etc. They have a
meaning per se, beyond constants.

Also, make clear an extension's railtie does not need to
be called "Railtie" or have "Railtie" in their class name.

1 files changed, 36 insertions, 36 deletions

diff --git a/railties/lib/rails/railtie.rb b/railties/lib/rails/railtie.rb
index 99dd571a00..d03f8324bc 100644
--- a/railties/lib/rails/railtie.rb
+++ b/railties/lib/rails/railtie.rb
@@ -5,34 +5,34 @@ 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 +45,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 +55,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 +63,54 @@ 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
   #
   # == 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"