diff --git a/railties/lib/rails/engine.rb b/railties/lib/rails/engine.rb
index 54c97258ce..c284840a38 100644
--- a/railties/lib/rails/engine.rb
+++ b/railties/lib/rails/engine.rb
@@ -20,7 +20,6 @@ module Rails
   #   # lib/my_engine.rb
   #   module MyEngine
   #     class Engine < Rails::Engine
-  #       engine_name :my_engine
   #     end
   #   end
   #
@@ -38,11 +37,12 @@ module Rails
   # Example:
   #
   #   class MyEngine < Rails::Engine
-  #     # config.middleware is shared configururation
-  #     config.middleware.use MyEngine::Middleware
-  #
   #     # Add a load path for this specific Engine
   #     config.load_paths << File.expand_path("../lib/some/path", __FILE__)
+  #
+  #     initializer "my_engine.add_middleware" do |app|
+  #       app.middlewares.use MyEngine::Middleware
+  #     end
   #   end
   # 
   # == Paths
diff --git a/railties/lib/rails/railtie.rb b/railties/lib/rails/railtie.rb
index 0d68abb323..6ac6be092e 100644
--- a/railties/lib/rails/railtie.rb
+++ b/railties/lib/rails/railtie.rb
@@ -39,7 +39,6 @@ module Rails
   #   # lib/my_gem/railtie.rb
   #   module MyGem
   #     class Railtie < Rails::Railtie
-  #       railtie_name :mygem
   #     end
   #   end
   # 
@@ -51,24 +50,8 @@ module Rails
   # 
   #   module MyGem
   #     class Railtie < Rails::Railtie
-  #       railtie_name :mygem
   #     end
   #   end
-  #   
-  # * Make sure your Gem loads the railtie.rb file if Rails is loaded first, an easy
-  #   way to check is by checking for the Rails constant which will exist if Rails
-  #   has started:
-  # 
-  #   # lib/my_gem.rb
-  #   module MyGem
-  #     require 'lib/my_gem/railtie' if defined?(Rails)
-  #   end
-  # 
-  # * Or instead of doing the require automatically, you can ask your users to require
-  #   it for you in their Gemfile:
-  # 
-  #   # #{USER_RAILS_ROOT}/Gemfile
-  #   gem "my_gem", :require_as => ["my_gem", "my_gem/railtie"]
   #
   # == Initializers
   #
@@ -82,13 +65,11 @@ module Rails
   #   end
   #
   # If specified, the block can also receive the application object, in case you 
-  # need to access some application specific configuration:
+  # need to access some application specific configuration, like middleware:
   #
   #   class MyRailtie < Rails::Railtie
   #     initializer "my_railtie.configure_rails_initialization" do |app|
-  #       if app.config.cache_classes
-  #         # some initialization behavior
-  #       end
+  #       app.middlewares.use MyRailtie::Middleware
   #     end
   #   end
   #
@@ -104,9 +85,6 @@ module Rails
   #     # Customize the ORM
   #     config.generators.orm :my_railtie_orm
   #
-  #     # Add a middleware
-  #     config.middlewares.use MyRailtie::Middleware
-  #
   #     # Add a to_prepare block which is executed once in production
   #     # and before which request in development
   #     config.to_prepare do
@@ -160,7 +138,7 @@ module Rails
   # By registering it:
   #
   #   class MyRailtie < Railtie
-  #     subscriber MyRailtie::Subscriber.new
+  #     subscriber :my_gem, MyRailtie::Subscriber.new
   #   end
   #
   # Take a look in Rails::Subscriber docs for more information.