Merge remote branch 'docrails/master'

24 files changed, 129 insertions, 138 deletions

diff --git a/actionpack/lib/action_controller/caching.rb b/actionpack/lib/action_controller/caching.rb
index 4105f9e14f..14137f2886 100644
--- a/actionpack/lib/action_controller/caching.rb
+++ b/actionpack/lib/action_controller/caching.rb
@@ -3,7 +3,7 @@ require 'uri'
 require 'set'
 
 module ActionController #:nodoc:
-  # Caching is a cheap way of speeding up slow applications by keeping the result of
+  # \Caching is a cheap way of speeding up slow applications by keeping the result of
   # calculations, renderings, and database calls around for subsequent requests.
   # Action Controller affords you three approaches in varying levels of granularity:
   # Page, Action, Fragment.
@@ -14,7 +14,7 @@ module ActionController #:nodoc:
   # Note: To turn off all caching and sweeping, set
   #   config.action_controller.perform_caching = false.
   #
-  # == Caching stores
+  # == \Caching stores
   #
   # All the caching stores from ActiveSupport::Cache are available to be used as backends
   # for Action Controller caching. This setting only affects action and fragment caching
diff --git a/actionpack/lib/action_controller/caching/actions.rb b/actionpack/lib/action_controller/caching/actions.rb
index 546f043c58..a3591eafbe 100644
--- a/actionpack/lib/action_controller/caching/actions.rb
+++ b/actionpack/lib/action_controller/caching/actions.rb
@@ -23,15 +23,15 @@ module ActionController #:nodoc:
     # Action caching internally uses the fragment caching and an around
     # filter to do the job. The fragment cache is named according to both
     # the current host and the path. So a page that is accessed at
-    # http://david.somewhere.com/lists/show/1 will result in a fragment named
-    # "david.somewhere.com/lists/show/1". This allows the cacher to
-    # differentiate between "david.somewhere.com/lists/" and
-    # "jamis.somewhere.com/lists/" -- which is a helpful way of assisting
+    # <tt>http://david.example.com/lists/show/1</tt> will result in a fragment named
+    # <tt>david.example.com/lists/show/1</tt>. This allows the cacher to
+    # differentiate between <tt>david.example.com/lists/</tt> and
+    # <tt>jamis.example.com/lists/</tt> -- which is a helpful way of assisting
     # the subdomain-as-account-key pattern.
     #
     # Different representations of the same resource, e.g.
-    # <tt>http://david.somewhere.com/lists</tt> and
-    # <tt>http://david.somewhere.com/lists.xml</tt>
+    # <tt>http://david.example.com/lists</tt> and
+    # <tt>http://david.example.com/lists.xml</tt>
     # are treated like separate requests and so are cached separately.
     # Keep in mind when expiring an action cache that
     # <tt>:action => 'lists'</tt> is not the same as
@@ -144,7 +144,7 @@ module ActionController #:nodoc:
         attr_reader :path, :extension
 
         # If +infer_extension+ is true, the cache path extension is looked up from the request's
-        # path & format. This is desirable when reading and writing the cache, but not when
+        # path and format. This is desirable when reading and writing the cache, but not when
         # expiring the cache - expire_action should expire the same files regardless of the
         # request format.
         def initialize(controller, options = {}, infer_extension = true)
diff --git a/actionpack/lib/action_controller/caching/fragments.rb b/actionpack/lib/action_controller/caching/fragments.rb
index 460273dac1..37c155b9cd 100644
--- a/actionpack/lib/action_controller/caching/fragments.rb
+++ b/actionpack/lib/action_controller/caching/fragments.rb
@@ -18,7 +18,7 @@ module ActionController #:nodoc:
     #
     #   <% cache(:action => "list", :action_suffix => "all_topics") do %>
     #
-    # That would result in a name such as "/topics/list/all_topics", avoiding conflicts with the action cache and with any fragments that use a
+    # That would result in a name such as <tt>/topics/list/all_topics</tt>, avoiding conflicts with the action cache and with any fragments that use a
     # different suffix. Note that the URL doesn't have to really exist or be callable - the url_for system is just used to generate unique
     # cache names that we can refer to when we need to expire the cache.
     #
@@ -28,7 +28,7 @@ module ActionController #:nodoc:
     module Fragments
       # Given a key (as described in <tt>expire_fragment</tt>), returns a key suitable for use in reading,
       # writing, or expiring a cached fragment. If the key is a hash, the generated key is the return
-      # value of url_for on that hash (without the protocol). All keys are prefixed with "views/" and uses
+      # value of url_for on that hash (without the protocol). All keys are prefixed with <tt>views/</tt> and uses
       # ActiveSupport::Cache.expand_cache_key for the expansion.
       def fragment_cache_key(key)
         ActiveSupport::Cache.expand_cache_key(key.is_a?(Hash) ? url_for(key).split("://").last : key, :views)
@@ -71,7 +71,7 @@ module ActionController #:nodoc:
       #
       # +key+ can take one of three forms:
       # * String - This would normally take the form of a path, like
-      #   <tt>"pages/45/notes"</tt>.
+      #   <tt>pages/45/notes</tt>.
       # * Hash - Treated as an implicit call to +url_for+, like
       #   <tt>{:controller => "pages", :action => "notes", :id => 45}</tt>
       # * Regexp - Will remove any fragment that matches, so
diff --git a/actionpack/lib/action_controller/metal.rb b/actionpack/lib/action_controller/metal.rb
index 2281c500c5..96ac138ba3 100644
--- a/actionpack/lib/action_controller/metal.rb
+++ b/actionpack/lib/action_controller/metal.rb
@@ -43,28 +43,28 @@ module ActionController
     end
   end
 
-  # ActionController::Metal provides a way to get a valid Rack application from a controller.
+  # Provides a way to get a valid Rack application from a controller.
   #
   # In AbstractController, dispatching is triggered directly by calling #process on a new controller.
-  # ActionController::Metal provides an #action method that returns a valid Rack application for a
-  # given action. Other rack builders, such as Rack::Builder, Rack::URLMap, and the Rails router,
-  # can dispatch directly to the action returned by FooController.action(:index).
+  # <tt>ActionController::Metal</tt> provides an <tt>action</tt> method that returns a valid Rack application for a
+  # given action. Other rack builders, such as Rack::Builder, Rack::URLMap, and the \Rails router,
+  # can dispatch directly to actions returned by controllers in your application.
   class Metal < AbstractController::Base
     abstract!
 
     attr_internal :env
 
     # Returns the last part of the controller's name, underscored, without the ending
-    # "Controller". For instance, MyApp::MyPostsController would return "my_posts" for
-    # controller_name
+    # <tt>Controller</tt>. For instance, PostsController returns <tt>posts</tt>.
+    # Namespaces are left out, so Admin::PostsController returns <tt>posts</tt> as well.
     #
     # ==== Returns
-    # String
+    # * <tt>string</tt>
     def self.controller_name
       @controller_name ||= self.name.demodulize.sub(/Controller$/, '').underscore
     end
 
-    # Delegates to the class' #controller_name
+    # Delegates to the class' <tt>controller_name</tt>
     def controller_name
       self.class.controller_name
     end
@@ -95,7 +95,7 @@ module ActionController
     # Basic implementations for content_type=, location=, and headers are
     # provided to reduce the dependency on the RackDelegation module
     # in Renderer and Redirector.
-
+    
     def content_type=(type)
       headers["Content-Type"] = type.to_s
     end
@@ -125,8 +125,7 @@ module ActionController
       super body
     end
 
-    # :api: private
-    def dispatch(name, request)
+    def dispatch(name, request) #:nodoc:
       @_request = request
       @_env = request.env
       @_env['action_controller.instance'] = self
@@ -134,8 +133,7 @@ module ActionController
       to_a
     end
 
-    # :api: private
-    def to_a
+    def to_a #:nodoc:
       response ? response.to_a : [status, headers, response_body]
     end
 
@@ -164,10 +162,10 @@ module ActionController
     # for the same action.
     #
     # ==== Parameters
-    # action<#to_s>:: An action name
+    # * <tt>action</tt> - An action name
     #
     # ==== Returns
-    # Proc:: A rack application
+    # * <tt>proc</tt> - A rack application
     def self.action(name, klass = ActionDispatch::Request)
       middleware_stack.build(name.to_s) do |env|
         new.dispatch(name, klass.new(env))
diff --git a/actionpack/lib/action_controller/metal/conditional_get.rb b/actionpack/lib/action_controller/metal/conditional_get.rb
index 61e7ece90d..797ad846f6 100644
--- a/actionpack/lib/action_controller/metal/conditional_get.rb
+++ b/actionpack/lib/action_controller/metal/conditional_get.rb
@@ -6,7 +6,7 @@ module ActionController
     include Head
 
     # Sets the etag, last_modified, or both on the response and renders a
-    # "304 Not Modified" response if the request is already fresh.
+    # <tt>304 Not Modified</tt> response if the request is already fresh.
     #
     # Parameters:
     # * <tt>:etag</tt>
@@ -21,7 +21,7 @@ module ActionController
     #   end
     #
     # This will render the show template if the request isn't sending a matching etag or
-    # If-Modified-Since header and just a "304 Not Modified" response if there's a match.
+    # If-Modified-Since header and just a <tt>304 Not Modified</tt> response if there's a match.
     #
     def fresh_when(options)
       options.assert_valid_keys(:etag, :last_modified, :public)
@@ -36,7 +36,7 @@ module ActionController
     # Sets the etag and/or last_modified on the response and checks it against
     # the client request. If the request doesn't match the options provided, the
     # request is considered stale and should be generated from scratch. Otherwise,
-    # it's fresh and we don't need to generate anything and a reply of "304 Not Modified" is sent.
+    # it's fresh and we don't need to generate anything and a reply of <tt>304 Not Modified</tt> is sent.
     #
     # Parameters:
     # * <tt>:etag</tt>
@@ -60,8 +60,8 @@ module ActionController
       !request.fresh?(response)
     end
 
-    # Sets a HTTP 1.1 Cache-Control header. Defaults to issuing a "private" instruction, so that
-    # intermediate caches shouldn't cache the response.
+    # Sets a HTTP 1.1 Cache-Control header. Defaults to issuing a <tt>private</tt> instruction, so that
+    # intermediate caches must not cache the response.
     #
     # Examples:
     #   expires_in 20.minutes
@@ -77,7 +77,7 @@ module ActionController
       response.cache_control[:extras] = options.map {|k,v| "#{k}=#{v}"}
     end
 
-    # Sets a HTTP 1.1 Cache-Control header of "no-cache" so no caching should occur by the browser or
+    # Sets a HTTP 1.1 Cache-Control header of <tt>no-cache</tt> so no caching should occur by the browser or
     # intermediate caches (like caching proxy servers).
     def expires_now #:doc:
       response.cache_control.replace(:no_cache => true)
diff --git a/actionpack/lib/action_controller/metal/helpers.rb b/actionpack/lib/action_controller/metal/helpers.rb
index e0bc47318a..4b6897c5dd 100644
--- a/actionpack/lib/action_controller/metal/helpers.rb
+++ b/actionpack/lib/action_controller/metal/helpers.rb
@@ -2,21 +2,21 @@ require 'active_support/core_ext/array/wrap'
 require 'active_support/core_ext/class/attribute'
 
 module ActionController
-  # The Rails framework provides a large number of helpers for working with +assets+, +dates+, +forms+,
-  # +numbers+ and model objects, to name a few. These helpers are available to all templates
+  # The \Rails framework provides a large number of helpers for working with assets, dates, forms,
+  # numbers and model objects, to name a few. These helpers are available to all templates
   # by default.
   #
-  # In addition to using the standard template helpers provided in the Rails framework, creating custom helpers to
+  # In addition to using the standard template helpers provided, creating custom helpers to
   # extract complicated logic or reusable functionality is strongly encouraged. By default, the controller will
   # include a helper whose name matches that of the controller, e.g., <tt>MyController</tt> will automatically
   # include <tt>MyHelper</tt>.
   #
-  # Additional helpers can be specified using the +helper+ class method in <tt>ActionController::Base</tt> or any
+  # Additional helpers can be specified using the +helper+ class method in ActionController::Base or any
   # controller which inherits from it.
   #
   # ==== Examples
-  # The +to_s+ method from the Time class can be wrapped in a helper method to display a custom message if
-  # the Time object is blank:
+  # The +to_s+ method from the \Time class can be wrapped in a helper method to display a custom message if
+  # a \Time object is blank:
   #
   #   module FormattedTimeHelper
   #     def format_time(time, format=:long, blank_message="&nbsp;")
@@ -71,12 +71,11 @@ module ActionController
       # Declares helper accessors for controller attributes. For example, the
       # following adds new +name+ and <tt>name=</tt> instance methods to a
       # controller and makes them available to the view:
-      #   helper_attr :name
       #   attr_accessor :name
+      #   helper_attr :name
       #
       # ==== Parameters
-      # *attrs<Array[String, Symbol]>:: Names of attributes to be converted
-      #   into helpers.
+      # * <tt>attrs</tt> - Names of attributes to be converted into helpers.
       def helper_attr(*attrs)
         attrs.flatten.each { |attr| helper_method(attr, "#{attr}=") }
       end
@@ -91,17 +90,16 @@ module ActionController
         # all helpers in helpers_dir.
         #
         # ==== Parameters
-        # args<Array[String, Symbol, Module, all]>:: A list of helpers
+        # * <tt>args</tt> - A list of helpers
         #
         # ==== Returns
-        # Array[Module]:: A normalized list of modules for the list of
-        #   helpers provided.
+        # * <tt>array</tt> - A normalized list of modules for the list of helpers provided.
         def modules_for_helpers(args)
           args += all_application_helpers if args.delete(:all)
           super(args)
         end
 
-        # Extract helper names from files in app/helpers/**/*_helper.rb
+        # Extract helper names from files in <tt>app/helpers/**/*_helper.rb</tt>
         def all_application_helpers
           helpers = []
           Array.wrap(helpers_path).each do |path|
diff --git a/actionpack/lib/action_controller/metal/hide_actions.rb b/actionpack/lib/action_controller/metal/hide_actions.rb
index 32d7a96701..b55c4643be 100644
--- a/actionpack/lib/action_controller/metal/hide_actions.rb
+++ b/actionpack/lib/action_controller/metal/hide_actions.rb
@@ -1,8 +1,7 @@
 require 'active_support/core_ext/class/attribute'
 
 module ActionController
-  # ActionController::HideActions adds the ability to prevent public methods on a controller
-  # to be called as actions.
+  # Adds the ability to prevent public methods on a controller to be called as actions.
   module HideActions
     extend ActiveSupport::Concern
 
@@ -23,7 +22,7 @@ module ActionController
       # Sets all of the actions passed in as hidden actions.
       #
       # ==== Parameters
-      # *args<#to_s>:: A list of actions
+      # * <tt>args</tt> - A list of actions
       def hide_action(*args)
         self.hidden_actions = hidden_actions.dup.merge(args.map(&:to_s)).freeze
       end
diff --git a/actionpack/lib/action_controller/metal/http_authentication.rb b/actionpack/lib/action_controller/metal/http_authentication.rb
index acd313b039..1d74521e4f 100644
--- a/actionpack/lib/action_controller/metal/http_authentication.rb
+++ b/actionpack/lib/action_controller/metal/http_authentication.rb
@@ -3,9 +3,9 @@ require 'active_support/core_ext/object/blank'
 
 module ActionController
   module HttpAuthentication
-    # Makes it dead easy to do HTTP Basic authentication.
+    # Makes it dead easy to do HTTP \Basic and \Digest authentication.
     #
-    # Simple Basic example:
+    # === Simple \Basic example
     #
     #   class PostsController < ApplicationController
     #     USER_NAME, PASSWORD = "dhh", "secret"
@@ -29,7 +29,9 @@ module ActionController
     #   end
     #
     #
-    # Here is a more advanced Basic example where only Atom feeds and the XML API is protected by HTTP authentication,
+    # === Advanced \Basic example
+    # 
+    # Here is a more advanced \Basic example where only Atom feeds and the XML API is protected by HTTP authentication,
     # the regular HTML interface is protected by a session approach:
     #
     #   class ApplicationController < ActionController::Base
@@ -69,7 +71,7 @@ module ActionController
     #     assert_equal 200, status
     #   end
     #
-    # Simple Digest example:
+    # === Simple \Digest example
     #
     #   require 'digest/md5'
     #   class PostsController < ApplicationController
@@ -95,18 +97,20 @@ module ActionController
     #       end
     #   end
     #
-    # NOTE: The +authenticate_or_request_with_http_digest+ block must return the user's password or the ha1 digest hash so the framework can appropriately
-    #       hash to check the user's credentials. Returning +nil+ will cause authentication to fail.
-    #       Storing the ha1 hash: MD5(username:realm:password), is better than storing a plain password. If
-    #       the password file or database is compromised, the attacker would be able to use the ha1 hash to
-    #       authenticate as the user at this +realm+, but would not have the user's password to try using at
-    #       other sites.
+    # === Notes
+    # 
+    # The +authenticate_or_request_with_http_digest+ block must return the user's password
+    # or the ha1 digest hash so the framework can appropriately hash to check the user's
+    # credentials. Returning +nil+ will cause authentication to fail.
     #
-    # On shared hosts, Apache sometimes doesn't pass authentication headers to
-    # FCGI instances. If your environment matches this description and you cannot
-    # authenticate, try this rule in your Apache setup:
+    # Storing the ha1 hash: MD5(username:realm:password), is better than storing a plain password. If
+    # the password file or database is compromised, the attacker would be able to use the ha1 hash to
+    # authenticate as the user at this +realm+, but would not have the user's password to try using at
+    # other sites.
     #
-    #   RewriteRule ^(.*)$ dispatch.fcgi [E=X-HTTP_AUTHORIZATION:%{HTTP:Authorization},QSA,L]
+    # In rare instances, web servers or front proxies strip authorization headers before
+    # they reach your application. You can debug this situation by logging all environment
+    # variables, and check for HTTP_AUTHORIZATION, amongst others.
     module Basic
       extend self
 
diff --git a/actionpack/lib/action_controller/metal/request_forgery_protection.rb b/actionpack/lib/action_controller/metal/request_forgery_protection.rb
index b632e7aab6..fc3118671f 100644
--- a/actionpack/lib/action_controller/metal/request_forgery_protection.rb
+++ b/actionpack/lib/action_controller/metal/request_forgery_protection.rb
@@ -4,45 +4,27 @@ module ActionController #:nodoc:
   class InvalidAuthenticityToken < ActionControllerError #:nodoc:
   end
 
-  # Protecting controller actions from CSRF attacks by ensuring that all forms are coming from the current
-  # web application, not a forged link from another site, is done by embedding a token based on a random
-  # string stored in the session (which an attacker wouldn't know) in all forms and Ajax requests generated
-  # by Rails and then verifying the authenticity of that token in the controller.  Only HTML/JavaScript
-  # requests are checked, so this will not protect your XML API (presumably you'll have a different
-  # authentication scheme there anyway).  Also, GET requests are not protected as these should be
-  # idempotent anyway.
+  # Controller actions are protected from Cross-Site Request Forgery (CSRF) attacks
+  # by including a token in the rendered html for your application. This token is
+  # stored as a random string in the session, to which an attacker does not have
+  # access. When a request reaches your application, \Rails then verifies the received
+  # token with the token in the session. Only HTML and javascript requests are checked,
+  # so this will not protect your XML API (presumably you'll have a different
+  # authentication scheme there anyway). Also, GET requests are not protected as these
+  # should be idempotent.
   #
-  # This is turned on with the <tt>protect_from_forgery</tt> method, which will check the token and raise an
-  # ActionController::InvalidAuthenticityToken if it doesn't match what was expected. You can customize the
-  # error message in production by editing public/422.html.  A call to this method in ApplicationController is
-  # generated by default in post-Rails 2.0 applications.
+  # CSRF protection is turned on with the <tt>protect_from_forgery</tt> method,
+  # which will check the token and raise an ActionController::InvalidAuthenticityToken
+  # if it doesn't match what was expected. A call to this method is generated for new
+  # \Rails applications by default. You can customize the error message by editing
+  # public/422.html. 
   #
-  # The token parameter is named <tt>authenticity_token</tt> by default. If you are generating an HTML form
-  # manually (without the use of Rails' <tt>form_for</tt>, <tt>form_tag</tt> or other helpers), you have to
-  # include a hidden field named like that and set its value to what is returned by
-  # <tt>form_authenticity_token</tt>.
-  #
-  # Request forgery protection is disabled by default in test environment. If you are upgrading from Rails
-  # 1.x, add this to config/environments/test.rb:
-  #
-  #   # Disable request forgery protection in test environment
-  #   config.action_controller.allow_forgery_protection = false
-  #
-  # == Learn more about CSRF (Cross-Site Request Forgery) attacks
-  #
-  # Here are some resources:
-  # * http://isc.sans.org/diary.html?storyid=1750
-  # * http://en.wikipedia.org/wiki/Cross-site_request_forgery
-  #
-  # Keep in mind, this is NOT a silver-bullet, plug 'n' play, warm security blanket for your rails application.
-  # There are a few guidelines you should follow:
-  #
-  # * Keep your GET requests safe and idempotent.  More reading material:
-  #   * http://www.xml.com/pub/a/2002/04/24/deviant.html
-  #   * http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
-  #   * Make sure the session cookies that Rails creates are non-persistent.  Check in Firefox and look
-  #     for "Expires: at end of session"
+  # The token parameter is named <tt>authenticity_token</tt> by default. The name and
+  # value of this token must be added to every layout that renders forms by including
+  # <tt>csrf_meta_tag</tt> in the html +head+.
   #
+  # Learn more about CSRF attacks and securing your application in the
+  # {Ruby on Rails Security Guide}[http://guides.rubyonrails.org/security.html].
   module RequestForgeryProtection
     extend ActiveSupport::Concern
 
diff --git a/actionpack/lib/action_controller/metal/responder.rb b/actionpack/lib/action_controller/metal/responder.rb
index aafba2a65f..851925e1b7 100644
--- a/actionpack/lib/action_controller/metal/responder.rb
+++ b/actionpack/lib/action_controller/metal/responder.rb
@@ -1,7 +1,7 @@
 require 'active_support/json'
 
 module ActionController #:nodoc:
-  # Responder is responsible for exposing a resource to different mime requests,
+  # Responsible for exposing a resource to different mime requests,
   # usually depending on the HTTP verb. The responder is triggered when
   # <code>respond_with</code> is called. The simplest case to study is a GET request:
   #
@@ -24,10 +24,10 @@ module ActionController #:nodoc:
   #
   # === Builtin HTTP verb semantics
   #
-  # The default Rails responder holds semantics for each HTTP verb. Depending on the
+  # The default \Rails responder holds semantics for each HTTP verb. Depending on the
   # content type, verb and the resource status, it will behave differently.
   #
-  # Using Rails default responder, a POST request for creating an object could
+  # Using \Rails default responder, a POST request for creating an object could
   # be written as:
   #
   #   def create
@@ -140,7 +140,7 @@ module ActionController #:nodoc:
 
   protected
 
-    # This is the common behavior for "navigation" requests, like :html, :iphone and so forth.
+    # This is the common behavior for formats associated with browsing, like :html, :iphone and so forth.
     def navigation_behavior(error)
       if get?
         raise error
@@ -151,7 +151,7 @@ module ActionController #:nodoc:
       end
     end
 
-    # This is the common behavior for "API" requests, like :xml and :json.
+    # This is the common behavior for formats associated with APIs, such as :xml and :json.
     def api_behavior(error)
       raise error unless resourceful?
 
diff --git a/actionpack/lib/action_controller/test_case.rb b/actionpack/lib/action_controller/test_case.rb
index 75ea6523f7..065152d01d 100644
--- a/actionpack/lib/action_controller/test_case.rb
+++ b/actionpack/lib/action_controller/test_case.rb
@@ -245,7 +245,7 @@ module ActionController
   #      after calling +post+. If the various assert methods are not sufficient, then you
   #      may use this object to inspect the HTTP response in detail.
   #
-  # (Earlier versions of Rails required each functional test to subclass
+  # (Earlier versions of \Rails required each functional test to subclass
   # Test::Unit::TestCase and define @controller, @request, @response in +setup+.)
   #
   # == Controller is automatically inferred
@@ -258,7 +258,7 @@ module ActionController
   #     tests WidgetController
   #   end
   #
-  # == Testing controller internals
+  # == \Testing controller internals
   #
   # In addition to these specific assertions, you also have easy access to various collections that the regular test/unit assertions
   # can be used against. These collections are:
@@ -266,7 +266,7 @@ module ActionController
   # * assigns: Instance variables assigned in the action that are available for the view.
   # * session: Objects being saved in the session.
   # * flash: The flash objects currently in the session.
-  # * cookies: Cookies being sent to the user on this request.
+  # * cookies: \Cookies being sent to the user on this request.
   #
   # These collections can be used just like any other hash:
   #
@@ -292,7 +292,7 @@ module ActionController
   #   @request.session[:key] = "value"
   #   @request.cookies["key"] = "value"
   #
-  # == Testing named routes
+  # == \Testing named routes
   #
   # If you're using named routes, they can be easily tested using the original named routes' methods straight in the test case.
   # Example:
diff --git a/actionpack/lib/action_dispatch/http/mime_negotiation.rb b/actionpack/lib/action_dispatch/http/mime_negotiation.rb
index 4082770b85..b959aa258e 100644
--- a/actionpack/lib/action_dispatch/http/mime_negotiation.rb
+++ b/actionpack/lib/action_dispatch/http/mime_negotiation.rb
@@ -32,7 +32,7 @@ module ActionDispatch
         end
       end
 
-      # Returns the Mime type for the \format used in the request.
+      # Returns the MIME type for the \format used in the request.
       #
       #   GET /posts/5.xml   | request.format => Mime::XML
       #   GET /posts/5.xhtml | request.format => Mime::HTML
diff --git a/actionpack/lib/action_dispatch/http/url.rb b/actionpack/lib/action_dispatch/http/url.rb
index ffb7bdd586..f6375902f6 100644
--- a/actionpack/lib/action_dispatch/http/url.rb
+++ b/actionpack/lib/action_dispatch/http/url.rb
@@ -1,7 +1,7 @@
 module ActionDispatch
   module Http
     module URL
-      # Returns the complete URL used for this request.
+      # Returns the complete \URL used for this request.
       def url
         protocol + host_with_port + fullpath
       end
@@ -96,7 +96,7 @@ module ActionDispatch
       end
 
       # Returns the request URI, accounting for server idiosyncrasies.
-      # WEBrick includes the full URL. IIS leaves REQUEST_URI blank.
+      # WEBrick includes the full \URL. IIS leaves REQUEST_URI blank.
       def request_uri
         ActiveSupport::Deprecation.warn "Using #request_uri is deprecated. Use fullpath instead.", caller
         fullpath
diff --git a/actionpack/lib/action_dispatch/middleware/cookies.rb b/actionpack/lib/action_dispatch/middleware/cookies.rb
index c281e323e5..75c8cc3dd0 100644
--- a/actionpack/lib/action_dispatch/middleware/cookies.rb
+++ b/actionpack/lib/action_dispatch/middleware/cookies.rb
@@ -7,7 +7,7 @@ module ActionDispatch
     end
   end
 
-  # Cookies are read and written through ActionController#cookies.
+  # \Cookies are read and written through ActionController#cookies.
   #
   # The cookies being read are the ones received along with the request, the cookies
   # being written will be sent out with the response. Reading a cookie does not get
@@ -21,6 +21,15 @@ module ActionDispatch
   #   # Sets a cookie that expires in 1 hour.
   #   cookies[:login] = { :value => "XJ-122", :expires => 1.hour.from_now }
   #
+  #   # Sets a signed cookie, which prevents a user from tampering with its value.
+  #   # You must specify a value in ActionController::Base.cookie_verifier_secret.
+  #   cookies.signed[:remember_me] = [current_user.id, current_user.salt]
+  #
+  #   # Sets a "permanent" cookie (which expires in 20 years from now).
+  #   cookies.permanent[:login] = "XJ-122"
+  #   # You can also chain these methods:
+  #   cookies.permanent.signed[:login] = "XJ-122"
+  #
   # Examples for reading:
   #
   #   cookies[:user_name] # => "david"
@@ -55,7 +64,7 @@ module ActionDispatch
   #     :domain => :all # Allow the cookie for the top most level
   #                       domain and subdomains.
   #
-  # * <tt>:expires</tt> - The time at which this cookie expires, as a Time object.
+  # * <tt>:expires</tt> - The time at which this cookie expires, as a \Time object.
   # * <tt>:secure</tt> - Whether this cookie is a only transmitted to HTTPS servers.
   #   Default is +false+.
   # * <tt>:httponly</tt> - Whether this cookie is accessible via scripting or
diff --git a/actionpack/lib/action_dispatch/middleware/flash.rb b/actionpack/lib/action_dispatch/middleware/flash.rb
index bfa30cf5af..21aeeb217a 100644
--- a/actionpack/lib/action_dispatch/middleware/flash.rb
+++ b/actionpack/lib/action_dispatch/middleware/flash.rb
@@ -10,13 +10,13 @@ module ActionDispatch
 
   # The flash provides a way to pass temporary objects between actions. Anything you place in the flash will be exposed
   # to the very next action and then cleared out. This is a great way of doing notices and alerts, such as a create
-  # action that sets <tt>flash[:notice] = "Successfully created"</tt> before redirecting to a display action that can
+  # action that sets <tt>flash[:notice] = "Post successfully created"</tt> before redirecting to a display action that can
   # then expose the flash to its template. Actually, that exposure is automatically done. Example:
   #
   #   class PostsController < ActionController::Base
   #     def create
   #       # save post
-  #       flash[:notice] = "Successfully created post"
+  #       flash[:notice] = "Post successfully created"
   #       redirect_to posts_path(@post)
   #     end
   #
@@ -30,6 +30,11 @@ module ActionDispatch
   #       <div class="notice"><%= flash[:notice] %></div>
   #     <% end %>
   #
+  # Since the +notice+ and +alert+ keys are a common idiom, convenience accessors are available:
+  #
+  #   flash.alert = "You must be logged in"
+  #   flash.notice = "Post successfully created"
+  #
   # This example just places a string in the flash, but you can put any object in there. And of course, you can put as
   # many as you like at a time too. Just remember: They'll be gone by the time the next action has been performed.
   #
diff --git a/actionpack/lib/action_dispatch/testing/assertions/dom.rb b/actionpack/lib/action_dispatch/testing/assertions/dom.rb
index 9c215de743..47c84742aa 100644
--- a/actionpack/lib/action_dispatch/testing/assertions/dom.rb
+++ b/actionpack/lib/action_dispatch/testing/assertions/dom.rb
@@ -3,7 +3,7 @@ require 'action_controller/vendor/html-scanner'
 module ActionDispatch
   module Assertions
     module DomAssertions
-      # Test two HTML strings for equivalency (e.g., identical up to reordering of attributes)
+      # \Test two HTML strings for equivalency (e.g., identical up to reordering of attributes)
       #
       # ==== Examples
       #
diff --git a/actionpack/lib/action_dispatch/testing/assertions/response.rb b/actionpack/lib/action_dispatch/testing/assertions/response.rb
index ec5e9efe44..10b122557a 100644
--- a/actionpack/lib/action_dispatch/testing/assertions/response.rb
+++ b/actionpack/lib/action_dispatch/testing/assertions/response.rb
@@ -1,6 +1,6 @@
 module ActionDispatch
   module Assertions
-    # A small suite of assertions that test responses from Rails applications.
+    # A small suite of assertions that test responses from \Rails applications.
     module ResponseAssertions
       extend ActiveSupport::Concern
 
@@ -18,8 +18,8 @@ module ActionDispatch
       # * <tt>:missing</tt>   - Status code was 404
       # * <tt>:error</tt>     - Status code was in the 500-599 range
       #
-      # You can also pass an explicit status number like assert_response(501)
-      # or its symbolic equivalent assert_response(:not_implemented).
+      # You can also pass an explicit status number like <tt>assert_response(501)</tt>
+      # or its symbolic equivalent <tt>assert_response(:not_implemented)</tt>.
       # See ActionDispatch::StatusCodes for a full list.
       #
       # ==== Examples
@@ -45,8 +45,8 @@ module ActionDispatch
       end
 
       # Assert that the redirection options passed in match those of the redirect called in the latest action.
-      # This match can be partial, such that assert_redirected_to(:controller => "weblog") will also
-      # match the redirection of redirect_to(:controller => "weblog", :action => "show") and so on.
+      # This match can be partial, such that <tt>assert_redirected_to(:controller => "weblog")</tt> will also
+      # match the redirection of <tt>redirect_to(:controller => "weblog", :action => "show")</tt> and so on.
       #
       # ==== Examples
       #
diff --git a/actionpack/lib/action_dispatch/testing/assertions/routing.rb b/actionpack/lib/action_dispatch/testing/assertions/routing.rb
index 5a3ffda255..c5fed1fc8f 100644
--- a/actionpack/lib/action_dispatch/testing/assertions/routing.rb
+++ b/actionpack/lib/action_dispatch/testing/assertions/routing.rb
@@ -4,10 +4,10 @@ require 'active_support/core_ext/hash/indifferent_access'
 
 module ActionDispatch
   module Assertions
-    # Suite of assertions to test routes generated by Rails and the handling of requests made to them.
+    # Suite of assertions to test routes generated by \Rails and the handling of requests made to them.
     module RoutingAssertions
       # Asserts that the routing of the given +path+ was handled correctly and that the parsed options (given in the +expected_options+ hash)
-      # match +path+.  Basically, it asserts that Rails recognizes the route given by +expected_options+.
+      # match +path+.  Basically, it asserts that \Rails recognizes the route given by +expected_options+.
       #
       # Pass a hash in the second argument (+path+) to specify the request method.  This is useful for routes
       # requiring a specific HTTP method.  The hash should contain a :path with the incoming request path
diff --git a/actionpack/lib/action_view/helpers/tag_helper.rb b/actionpack/lib/action_view/helpers/tag_helper.rb
index 5d032b32a7..1b9e152b4d 100644
--- a/actionpack/lib/action_view/helpers/tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/tag_helper.rb
@@ -16,7 +16,7 @@ module ActionView
                            autoplay controls loop selected hidden scoped async
                            defer reversed ismap seemless muted required
                            autofocus novalidate formnovalidate open).to_set
-      BOOLEAN_ATTRIBUTES.merge(BOOLEAN_ATTRIBUTES.map {|attr| attr.to_sym })
+      BOOLEAN_ATTRIBUTES.merge(BOOLEAN_ATTRIBUTES.map {|attribute| attribute.to_sym })
 
       # Returns an empty HTML tag of type +name+ which by default is XHTML
       # compliant. Set +open+ to true to create an open tag compatible
diff --git a/activesupport/lib/active_support/deprecation/proxy_wrappers.rb b/activesupport/lib/active_support/deprecation/proxy_wrappers.rb
index deb33ab702..970536a594 100644
--- a/activesupport/lib/active_support/deprecation/proxy_wrappers.rb
+++ b/activesupport/lib/active_support/deprecation/proxy_wrappers.rb
@@ -58,7 +58,7 @@ module ActiveSupport
         end
     end
 
-    class DeprecatedConstantProxy < DeprecationProxy #:nodoc:
+    class DeprecatedConstantProxy < DeprecationProxy #:nodoc:all
       def initialize(old_const, new_const)
         @old_const = old_const
         @new_const = new_const
diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile
index e242cdaf73..459d70f111 100644
--- a/railties/guides/source/action_view_overview.textile
+++ b/railties/guides/source/action_view_overview.textile
@@ -428,7 +428,7 @@ A method for caching fragments of a view rather than an entire action or page. T
 
 <ruby>
 <% cache do %>
-  <%= render :partial => "shared/footer" %>
+  <%= render "shared/footer" %>
 <% end %>
 </ruby>
 
diff --git a/railties/guides/source/active_record_validations_callbacks.textile b/railties/guides/source/active_record_validations_callbacks.textile
index 9bdeecb684..a8ccfc7e40 100644
--- a/railties/guides/source/active_record_validations_callbacks.textile
+++ b/railties/guides/source/active_record_validations_callbacks.textile
@@ -197,7 +197,7 @@ end
 
 This validation will work with all of the association types.
 
-CAUTION: Don't use +validates_associated+ on both ends of your associations, they would call each other in an infinite loop.
+CAUTION: Don't use +validates_associated+ on both ends of your associations. They would call each other in an infinite loop.
 
 The default error message for +validates_associated+ is "_is invalid_". Note that each associated object will contain its own +errors+ collection; errors do not bubble up to the calling model.
 
diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile
index 399cba58bb..49c1049cc7 100644
--- a/railties/guides/source/getting_started.textile
+++ b/railties/guides/source/getting_started.textile
@@ -194,7 +194,7 @@ In any case, Rails will create a folder in your working directory called <tt>blo
 
 h4. Installing the Required Gems
 
-Rails applications manage gem dependencies with "Bundler":http://www.github.com/carlhuda/bundler by default. As we don't need any other gems beyond the ones in the generated +Gemfile+ we can directly run
+Rails applications manage gem dependencies with "Bundler":http://gembundler.com/v1.0/index.html by default. As we don't need any other gems beyond the ones in the generated +Gemfile+ we can directly run
 
 <shell>
 bundle install
@@ -320,7 +320,7 @@ $ rm public/index.html
 
 We need to do this as Rails will deliver any static file in the +public+ directory in preference to any dynamic contact we generate from the controllers.
 
-Now, you have to tell Rails where your actual home page is located. Open the file +config/routes.rb+ in your editor. This is your application's _routing file_ which holds entries in a special DSL (domain-specific language) that tells Rails how to connect incoming requests to controllers and actions. This file contains many sample routes on commented lines, and one of them actually shows you how to connect the root of your site to a specific controller and action. Find the line beginning with +:root to+, uncomment it and change it like the following:
+Now, you have to tell Rails where your actual home page is located. Open the file +config/routes.rb+ in your editor. This is your application's _routing file_ which holds entries in a special DSL (domain-specific language) that tells Rails how to connect incoming requests to controllers and actions. This file contains many sample routes on commented lines, and one of them actually shows you how to connect the root of your site to a specific controller and action. Find the line beginning with +root :to+, uncomment it and change it like the following:
 
 <ruby>
 Blog::Application.routes.draw do
@@ -1056,8 +1056,7 @@ Then in the +app/views/posts/show.html.erb+ you can change it to look like the f
 </p>
 
 <h2>Comments</h2>
-<%= render :partial => "comments/comment",
-           :collection => @post.comments %>
+<%= render @post.comments %>
 
 <h2>Add a comment:</h2>
 <%= form_for([@post, @post.comments.build]) do |f| %>
@@ -1127,8 +1126,7 @@ Then you make the +app/views/posts/show.html.erb+ look like the following:
 </p>
 
 <h2>Comments</h2>
-<%= render :partial => "comments/comment",
-           :collection => @post.comments %>
+<%= render @post.comments %>
 
 <h2>Add a comment:</h2>
 <%= render "comments/form" %>
@@ -1381,8 +1379,7 @@ Finally, we will edit the <tt>app/views/posts/show.html.erb</tt> template to sho
 </p>
 
 <h2>Comments</h2>
-<%= render :partial => "comments/comment",
-           :collection => @post.comments %>
+<%= render @post.comments %>
 
 <h2>Add a comment:</h2>
 <%= render "comments/form" %>
@@ -1436,8 +1433,7 @@ Now you can edit the view in <tt>app/views/posts/show.html.erb</tt> to look like
 </p>
 
 <h2>Comments</h2>
-<%= render :partial => "comments/comment",
-           :collection => @post.comments %>
+<%= render @post.comments %>
 
 <h2>Add a comment:</h2>
 <%= render "comments/form" %>
diff --git a/railties/guides/source/performance_testing.textile b/railties/guides/source/performance_testing.textile
index 65f8d07e7a..7b21485ea0 100644
--- a/railties/guides/source/performance_testing.textile
+++ b/railties/guides/source/performance_testing.textile
@@ -469,7 +469,7 @@ And in "views":http://api.rubyonrails.org/classes/ActionController/Benchmarking/
 
 <erb>
 <% benchmark("Showing projects partial") do %>
-  <%= render :partial => @projects %>
+  <%= render @projects %>
 <% end %>
 </erb>