Copy-edit and format Rails::Engine docs.

1 files changed, 93 insertions, 85 deletions

diff --git a/railties/lib/rails/engine.rb b/railties/lib/rails/engine.rb
index 1d81e08cd3..b945df5703 100644
--- a/railties/lib/rails/engine.rb
+++ b/railties/lib/rails/engine.rb
@@ -5,19 +5,20 @@ require 'rbconfig'
 require 'rails/engine/railties'
 
 module Rails
-  # Rails::Engine allows you to wrap a specific Rails application and share it accross
-  # different applications. Since Rails 3.0, every Rails::Application is nothing
-  # more than an Engine, allowing you to share it very easily.
+  # Rails::Engine allows you to wrap a specific Rails application and share it across
+  # different applications. Since Rails 3.0, every <tt>Rails::Application</tt> is nothing
+  # more than an <tt>Engine</tt>, allowing you to share it very easily.
   #
-  # Any Rails::Engine is also a Rails::Railtie, so the same methods (like rake_tasks and
-  # generators) and configuration available in the latter can also be used in the former.
+  # Any <tt>Rails::Engine</tt> is also a <tt>Rails::Railtie</tt>, so the same methods
+  # (like <tt>rake_tasks</tt> and <tt>generators</tt>) and configuration available in the
+  # latter can also be used in the former.
   #
   # == Creating an Engine
   #
-  # In Rails versions before to 3.0, your gems automatically behaved as Engine, however
+  # In Rails versions prior to 3.0, your gems automatically behaved as Engines, however,
   # this coupled Rails to Rubygems. Since Rails 3.0, if you want a gem to automatically
-  # behave as Engine, you have to specify an Engine for it somewhere inside your plugin
-  # lib folder (similar to how we specify a Railtie):
+  # behave as an <tt>Engine</tt>, you have to specify an <tt>Engine</tt> for it somewhere
+  # inside your plugin's <tt>lib</tt> folder (similar to how we specify a <tt>Railtie</tt>):
   #
   #   # lib/my_engine.rb
   #   module MyEngine
@@ -25,16 +26,17 @@ module Rails
   #     end
   #   end
   #
-  # Then ensure that this file is loaded at the top of your config/application.rb (or in
-  # your Gemfile) and it will automatically load models, controllers and helpers
-  # inside app, load routes at "config/routes.rb", load locales at "config/locales/*",
-  # load tasks at "lib/tasks/*".
+  # Then ensure that this file is loaded at the top of your <tt>config/application.rb</tt>
+  # (or in your <tt>Gemfile</tt>) and it will automatically load models, controllers and helpers
+  # inside <tt>app</tt>, load routes at <tt>config/routes.rb</tt>, load locales at 
+  # <tt>config/locales/*</tt>, and load tasks at <tt>lib/tasks/*</tt>.
   #
   # == Configuration
   #
-  # Besides the Railtie configuration which is shared across the application, in a
-  # Rails::Engine you can access autoload_paths, eager_load_paths and autoload_once_paths,
-  # which differently from a Railtie, are scoped to the current Engine.
+  # Besides the <tt>Railtie</tt> configuration which is shared across the application, in a
+  # <tt>Rails::Engine</tt> you can access <tt>autoload_paths</tt>, <tt>eager_load_paths</tt>
+  # and <tt>autoload_once_paths</tt>, which, differently from a <tt>Railtie</tt>, are scoped to
+  # the current <tt>Engine</tt>.
   #
   # Example:
   #
@@ -49,7 +51,7 @@ module Rails
   #
   # == Generators
   #
-  # You can set up generators for engine with config.generators method:
+  # You can set up generators for Engines with <tt>config.generators</tt> method:
   #
   #   class MyEngine < Rails::Engine
   #     config.generators do |g|
@@ -59,7 +61,7 @@ module Rails
   #     end
   #   end
   #
-  # You can also set generators for application by using config.app_generators:
+  # You can also set generators for application by using <tt>config.app_generators</tt>:
   #
   #   class MyEngine < Rails::Engine
   #     # note that you can also pass block to app_generators in the same way you
@@ -70,18 +72,18 @@ module Rails
   # == Paths
   #
   # Since Rails 3.0, both your Application and Engines do not have hardcoded paths.
-  # This means that you are not required to place your controllers at "app/controllers",
+  # This means that you are not required to place your controllers at <tt>app/controllers</tt>,
   # but in any place which you find convenient.
   #
-  # For example, let's suppose you want to lay your controllers at lib/controllers, all
-  # you need to do is:
+  # For example, let's suppose you want to place your controllers in <tt>lib/controllers. 
+  # All you would need to do is:
   #
   #   class MyEngine < Rails::Engine
   #     paths["app/controllers"] = "lib/controllers"
   #   end
   #
-  # You can also have your controllers being loaded from both "app/controllers" and
-  # "lib/controllers":
+  # You can also have your controllers loaded from both <tt>app/controllers</tt> and
+  # <tt>lib/controllers</tt>:
   #
   #   class MyEngine < Rails::Engine
   #     paths["app/controllers"] << "lib/controllers"
@@ -103,32 +105,33 @@ module Rails
   #     paths["config/routes"]       #=> ["config/routes.rb"]
   #   end
   #
-  # Your Application class adds a couple more paths to this set. And as in your Application,
-  # all folders under "app" are automatically added to the load path. So if you have
-  # "app/observers", it's added by default.
+  # Your <tt>Application</tt> class adds a couple more paths to this set. And as in your 
+  # <tt>Application</tt>,all folders under <tt>app</tt> are automatically added to the load path. 
+  # So if you have <tt>app/observers</tt>, it's added by default.
   #
   # == Endpoint
   #
-  # Engine can be also a rack application. It can be useful if you have a rack application that
+  # An Engine can be also a rack application. It can be useful if you have a rack application that
   # you would like to wrap with Engine and provide some of the Engine's features.
   #
-  # To do that, use endpoint method:
+  # To do that, use the <tt>endpoint</tt> method:
+  #
   #   module MyEngine
   #     class Engine < Rails::Engine
   #       endpoint MyRackApplication
   #     end
   #   end
   #
-  # Now you can mount your engine in application's routes just like that:
+  # Now you can mount your <tt>Engine</tt> in application's routes just like that:
   #
-  # MyRailsApp::Application.routes.draw do
-  #   mount MyEngine::Engine => "/engine"
-  # end
+  #   MyRailsApp::Application.routes.draw do
+  #     mount MyEngine::Engine => "/engine"
+  #   end
   #
   # == Middleware stack
   #
-  # As Engine can now be rack endpoint, it can also have a middleware stack. The usage is exactly
-  # the same as in application:
+  # As <tt>Engine</tt> can now be rack endpoint, it can also have a middleware stack. The usage is exactly
+  # the same as in <tt>Application</tt>:
   #
   #   module MyEngine
   #     class Engine < Rails::Engine
@@ -148,30 +151,31 @@ module Rails
   #
   # == Mount priority
   #
-  # Note that now there can be more than one router in you application and it's better to avoid
-  # passing requests through many routers. Consider such situation:
+  # Note that now there can be more than one router in your application, and it's better to avoid
+  # passing requests through many routers. Consider this situation:
   #
   #   MyRailsApp::Application.routes.draw do
   #     mount MyEngine::Engine => "/blog"
   #     match "/blog/omg" => "main#omg"
   #   end
   #
-  # MyEngine is mounted at "/blog" path and additionaly "/blog/omg" points application's controller.
-  # In such situation request to "/blog/omg" will go through MyEngine and if there is no such route
-  # in Engine's routes, it will be dispatched to "main#omg". It's much better to swap that:
+  # <tt>MyEngine</tT> is mounted at <tt>/blog</tt>, and <tt>/blog/omg</tt> points to application's
+  # controller. In such a situation, requests to <tt>/blog/omg</tt> will go through <tt>MyEngine</tt>,
+  # and if there is no such route in Engine's routes, it will be dispatched to <tt>main#omg</tt>.
+  # It's much better to swap that:
   #
   #   MyRailsApp::Application.routes.draw do
   #     match "/blog/omg" => "main#omg"
   #     mount MyEngine::Engine => "/blog"
   #   end
   #
-  # Now, Engine will get only requests that were not handled by application.
+  # Now, </tt>Engine</tt> will get only requests that were not handled by <tt>Application</tt>.
   #
   # == Asset path
   #
-  # When you use engine with its own public directory, you will probably want to copy or symlink it
-  # to application's public directory. To simplify generating paths for assets, you can set asset_path
-  # for an Engine:
+  # When you use <tt>Engine</tt> with its own public directory, you will probably want to copy or symlink it
+  # to application's public directory. To simplify generating paths for assets, you can set <tt>asset_path</tt>
+  # for an <tt>Engine</tt>:
   #
   #   module MyEngine
   #     class Engine < Rails::Engine
@@ -179,27 +183,30 @@ module Rails
   #     end
   #   end
   #
-  # With such config, asset paths will be automatically modified inside Engine:
-  # image_path("foo.jpg") #=> "/my_engine/images/foo.jpg"
+  # With such a config, asset paths will be automatically modified inside <tt>Engine</tt>:
+  #
+  #   image_path("foo.jpg") #=> "/my_engine/images/foo.jpg"
   #
   # == Serving static files
   #
-  # By default, rails use ActionDispatch::Static to serve static files in development mode. This is ok
+  # By default, Rails uses <tt>ActionDispatch::Static</tt> to serve static files in development mode. This is ok
   # while you develop your application, but when you want to deploy it, assets from engine will not be
   # served by default. You should choose one of the two following strategies:
   #
   # * enable serving static files by setting config.serve_static_assets to true
-  # * copy engine's public files to application's public folder with rake ENGINE_NAME:install:assets, for example
-  #   rake my_engine:install:assets
+  # * copy engine's public files to application's public folder with <tt>rake ENGINE_NAME:install:assets</tt>, for example
+  #   <tt>rake my_engine:install:assets</tt>
   #
   # == Engine name
   #
-  # There are some places where engine's name is used:
-  # * routes: when you mount engine with mount(MyEngine::Engine => '/my_engine'), it's used as default :as option
-  # * some of the rake tasks are based on engine name, e.g. my_engine:install:migrations, my_engine:install:assets
+  # There are some places where an Engine's name is used:
+  # * routes: when you mount an Engine with <tt>mount(MyEngine::Engine => '/my_engine')</tt>,
+  #   it's used as default :as option
+  # * some of the rake tasks are based on engine name, e.g. <tt>my_engine:install:migrations</tt>,
+  #   <tt>my_engine:install:assets</tt>
   #
-  # Engine name is set by default based on class name. For MyEngine::Engine it will be my_engine_engine.
-  # You can change it manually it manually using engine_name method:
+  # Engine name is set by default based on class name. For <tt>MyEngine::Engine</tt> it will be
+  # <tt>my_engine_engine</tt>. You can change it manually it manually using the <tt>engine_name</tt> method:
   #
   #   module MyEngine
   #     class Engine < Rails::Engine
@@ -209,12 +216,12 @@ module Rails
   #
   # == Isolated Engine
   #
-  # Normally when you create controllers, helpers and models inside engine, they are treated
-  # as they were created inside the application. This means all applications helpers and named routes
-  # will be available to your engine controllers.
+  # Normally when you create controllers, helpers and models inside an engine, they are treated
+  # as they were created inside the application. This means all application helpers and named routes
+  # will be available to your engine's controllers.
   #
-  # However, sometimes you want to isolate your engine from the application, specially if your engine
-  # have its own router. To do that, you simply need to call +isolate_namespace+. This method requires
+  # However, sometimes you want to isolate your engine from the application, especially if your engine
+  # has its own router. To do that, you simply need to call +isolate_namespace+. This method requires
   # you to pass a module where all your controllers, helpers and models should be nested to:
   #
   #   module MyEngine
@@ -223,7 +230,8 @@ module Rails
   #     end
   #   end
   #
-  # With such Engine, everything that is inside MyEngine module, will be isolated from application.
+  # With such an Engine, everything that is inside the +MyEngine+ module will be isolated from
+  # the application.
   #
   # Consider such controller:
   #
@@ -232,24 +240,24 @@ module Rails
   #     end
   #   end
   #
-  # If engine is marked as isolated, FooController has access only to helpers from engine and
-  # url_helpers from MyEngine::Engine.routes.
+  # If engine is marked as isolated, +FooController+ has access only to helpers from engine and
+  # <tt>url_helpers</tt> from <tt>MyEngine::Engine.routes</tt>.
   #
-  # The next thing that changes in isolated engine is routes behaviour. Normally, when you namespace
-  # your controllers, you also need to do namespace all your routes. With isolated engine,
+  # The next thing that changes in isolated engines is the behaviour of routes. Normally, when you namespace
+  # your controllers, you also need to do namespace all your routes. With an isolated engine,
   # the namespace is applied by default, so you can ignore it in routes:
   #
   #   MyEngine::Engine.routes.draw do
   #     resources :articles
   #   end
-  # 
-  # The routes above will automatically point to MyEngine::ApplicationContoller. Further more, you don't
-  # need to use longer url helpers like "my_engine_articles_path". Instead, you shuold simply use
-  # articles_path as you would do with your application.
-  #
-  # To make that behaviour consistent with other parts of framework, isolated engine has influence also on
-  # ActiveModel::Naming. When you use namespaced model, like MyEngine::Article, it will normally
-  # use the prefix "my_engine". In isolated engine, the prefix will be ommited in url helpers and
+  #
+  # The routes above will automatically point to <tt>MyEngine::ApplicationContoller</tt>. Furthermore, you don't
+  # need to use longer url helpers like <tt>my_engine_articles_path</tt>. Instead, you shuold simply use
+  # <tt>articles_path</tt> as you would do with your application.
+  #
+  # To make that behaviour consistent with other parts of the framework, an isolated engine also has influence on
+  # <tt>ActiveModel::Naming</tt>. When you use a namespaced model, like <tt>MyEngine::Article</tt>, it will normally
+  # use the prefix "my_engine". In an isolated engine, the prefix will be ommited in url helpers and
   # form fields for convenience.
   #
   #   polymorphic_url(MyEngine::Article.new) #=> "articles_path"
@@ -264,9 +272,9 @@ module Rails
   #
   # == Using Engine's routes outside Engine
   #
-  # Since now you can mount engine inside application's routes, you do not have direct access to engine's
-  # url_helpers inside application. When you mount Engine in application's routes, a special helper is
-  # created to allow you to do that. Consider such scenario:
+  # Since you can now mount engine inside application's routes, you do not have direct access to engine's
+  # <tt>url_helpers</tt> inside application. When you mount Engine in application's routes, a special helper is
+  # created to allow you to do that. Consider such a scenario:
   #
   #   # APP/config/routes.rb
   #   MyApplication::Application.routes.draw do
@@ -274,7 +282,7 @@ module Rails
   #     match "/foo" => "foo#index"
   #   end
   #
-  # Now, you can use my_engine helper inside your application:
+  # Now, you can use the <tt>my_engine</tt> helper inside your application:
   #
   #   class FooController < ApplicationController
   #     def index
@@ -282,7 +290,7 @@ module Rails
   #     end
   #   end
   #
-  # There is also 'main_app' helper that gives you access to application's routes inside Engine:
+  # There is also a <tt>main_app</tt> helper that gives you access to application's routes inside Engine:
   #
   #   module MyEngine
   #     class BarController
@@ -292,34 +300,34 @@ module Rails
   #     end
   #   end
   #
-  # Note that the :as option given to mount takes the engine_name as default, so most of the time
-  # you can simply ommit it.
+  # Note that the <tt>:as</tt> option given to mount takes the <tt>engine_name</tT> as default, so most of the time
+  # you can simply omit it.
   #
-  # Finally, if you want to generate url to engine's route using polymorphic_url, you also need
+  # Finally, if you want to generate a url to engine's route using <tt>polymorphic_url</tt>, you also need
   # to pass the engine helper. Let's say that you want to create a form pointing to one of the
   # engine's routes. All you need to do is pass the helper as the first element in array with
   # attributes for url:
   #
-  # form_for([my_engine, @user])
+  #   form_for([my_engine, @user])
   #
-  # This code will use my_engine.user_path(@user) to generate the proper route.
+  # This code will use <tt>my_engine.user_path(@user)</tt> to generate the proper route.
   #
   # == Migrations & seed data
   #
-  # Engines can have their own migrations. Default path for migrations is exactly the same
-  # as in application: db/migrate
+  # Engines can have their own migrations. The default path for migrations is exactly the same
+  # as in application: <tt>db/migrate</tt>
   #
   # To use engine's migrations in application you can use rake task, which copies them to
   # application's dir:
   #
   #   rake ENGINE_NAME:install:migrations
   #
-  # Note that some of the migrations may be skipped if migration with the same name already exists
-  # in application. In such situation you must decide whether to leave that migration or rename the
+  # Note that some of the migrations may be skipped if a migration with the same name already exists
+  # in application. In such a situation you must decide whether to leave that migration or rename the
   # migration in application and rerun copying migrations.
   #
   # If your engine has migrations, you may also want to prepare data for the database in
-  # seeds.rb file. You can load that data using load_seed method, e.g.
+  # the <tt>seeds.rb</tt> file. You can load that data using the <tt>load_seed</tt> method, e.g.
   #
   #   MyEngine::Engine.load_seed
   #