Merge docrails.

Signed-off-by: Pratik Naik <pratiknaik@gmail.com>

26 files changed, 295 insertions, 283 deletions

diff --git a/actionpack/lib/action_controller/assertions/model_assertions.rb b/actionpack/lib/action_controller/assertions/model_assertions.rb
index 0b4313055a..d25214bb66 100644
--- a/actionpack/lib/action_controller/assertions/model_assertions.rb
+++ b/actionpack/lib/action_controller/assertions/model_assertions.rb
@@ -1,7 +1,8 @@
 module ActionController
   module Assertions
     module ModelAssertions
-      # Ensures that the passed record is valid by ActiveRecord standards and returns any error messages if it is not.
+      # Ensures that the passed record is valid by Active Record standards and
+      # returns any error messages if it is not.
       #
       # ==== Examples
       #
diff --git a/actionpack/lib/action_controller/assertions/routing_assertions.rb b/actionpack/lib/action_controller/assertions/routing_assertions.rb
index 2acd003243..491b72d586 100644
--- a/actionpack/lib/action_controller/assertions/routing_assertions.rb
+++ b/actionpack/lib/action_controller/assertions/routing_assertions.rb
@@ -59,7 +59,7 @@ module ActionController
         end
       end
 
-      # Asserts that the provided options can be used to generate the provided path.  This is the inverse of #assert_recognizes.
+      # Asserts that the provided options can be used to generate the provided path.  This is the inverse of +assert_recognizes+.
       # The +extras+ parameter is used to tell the request the names and values of additional request parameters that would be in
       # a query string. The +message+ parameter allows you to specify a custom error message for assertion failures.
       #
@@ -96,8 +96,8 @@ module ActionController
       end
 
       # Asserts that path and options match both ways; in other words, it verifies that <tt>path</tt> generates 
-      # <tt>options</tt> and then that <tt>options</tt> generates <tt>path</tt>.  This essentially combines #assert_recognizes 
-      # and #assert_generates into one step.
+      # <tt>options</tt> and then that <tt>options</tt> generates <tt>path</tt>.  This essentially combines +assert_recognizes+
+      # and +assert_generates+ into one step.
       #
       # The +extras+ hash allows you to specify options that would normally be provided as a query string to the action.  The
       # +message+ parameter allows you to specify a custom error message to display upon failure.  
diff --git a/actionpack/lib/action_controller/assertions/selector_assertions.rb b/actionpack/lib/action_controller/assertions/selector_assertions.rb
index 9ef093acfc..d3594e711c 100644
--- a/actionpack/lib/action_controller/assertions/selector_assertions.rb
+++ b/actionpack/lib/action_controller/assertions/selector_assertions.rb
@@ -12,12 +12,12 @@ module ActionController
       NO_STRIP = %w{pre script style textarea}
     end
 
-    # Adds the #assert_select method for use in Rails functional
+    # Adds the +assert_select+ method for use in Rails functional
     # test cases, which can be used to make assertions on the response HTML of a controller
-    # action. You can also call #assert_select within another #assert_select to
+    # action. You can also call +assert_select+ within another +assert_select+ to
     # make assertions on elements selected by the enclosing assertion.
     #
-    # Use #css_select to select elements without making an assertions, either
+    # Use +css_select+ to select elements without making an assertions, either
     # from the response HTML or elements selected by the enclosing assertion.
     # 
     # In addition to HTML responses, you can make the following assertions:
@@ -44,8 +44,8 @@ module ActionController
       # base element and any of its children. Returns an empty array if no
       # match is found.
       #
-      # The selector may be a CSS selector expression (+String+), an expression
-      # with substitution values (+Array+) or an HTML::Selector object.
+      # The selector may be a CSS selector expression (String), an expression
+      # with substitution values (Array) or an HTML::Selector object.
       #
       # ==== Examples
       #   # Selects all div tags
@@ -114,8 +114,8 @@ module ActionController
       # starting from (and including) that element and all its children in
       # depth-first order.
       #
-      # If no element if specified, calling #assert_select will select from the
-      # response HTML. Calling #assert_select inside an #assert_select block will
+      # If no element if specified, calling +assert_select+ will select from the
+      # response HTML. Calling #assert_select inside an +assert_select+ block will
       # run the assertion for each element selected by the enclosing assertion.
       #
       # ==== Example
@@ -130,7 +130,7 @@ module ActionController
       #     assert_select "li"
       #   end
       #
-      # The selector may be a CSS selector expression (+String+), an expression
+      # The selector may be a CSS selector expression (String), an expression
       # with substitution values, or an HTML::Selector object.
       #
       # === Equality Tests
@@ -356,16 +356,16 @@ module ActionController
       #
       # === Using blocks
       #
-      # Without a block, #assert_select_rjs merely asserts that the response
+      # Without a block, +assert_select_rjs+ merely asserts that the response
       # contains one or more RJS statements that replace or update content.
       #
-      # With a block, #assert_select_rjs also selects all elements used in
+      # With a block, +assert_select_rjs+ also selects all elements used in
       # these statements and passes them to the block. Nested assertions are
       # supported.
       #
-      # Calling #assert_select_rjs with no arguments and using nested asserts
+      # Calling +assert_select_rjs+ with no arguments and using nested asserts
       # asserts that the HTML content is returned by one or more RJS statements.
-      # Using #assert_select directly makes the same assertion on the content,
+      # Using +assert_select+ directly makes the same assertion on the content,
       # but without distinguishing whether the content is returned in an HTML
       # or JavaScript.
       #
@@ -601,7 +601,7 @@ module ActionController
           RJS_PATTERN_UNICODE_ESCAPED_CHAR = /\\u([0-9a-zA-Z]{4})/
         end
 
-        # #assert_select and #css_select call this to obtain the content in the HTML
+        # +assert_select+ and +css_select+ call this to obtain the content in the HTML
         # page, or from all the RJS statements, depending on the type of response.
         def response_from_page_or_rjs()
           content_type = @response.content_type
diff --git a/actionpack/lib/action_controller/assertions/tag_assertions.rb b/actionpack/lib/action_controller/assertions/tag_assertions.rb
index 4ac489520a..90ba3668fb 100644
--- a/actionpack/lib/action_controller/assertions/tag_assertions.rb
+++ b/actionpack/lib/action_controller/assertions/tag_assertions.rb
@@ -91,7 +91,7 @@ module ActionController
       #              :descendant => { :tag => "span",
       #                               :child => /hello world/ }
       #
-      # <b>Please note</b>: #assert_tag and #assert_no_tag only work
+      # <b>Please note</b>: +assert_tag+ and +assert_no_tag+ only work
       # with well-formed XHTML. They recognize a few tags as implicitly self-closing
       # (like br and hr and such) but will not work correctly with tags
       # that allow optional closing tags (p, li, td). <em>You must explicitly
@@ -104,8 +104,8 @@ module ActionController
         end
       end
       
-      # Identical to #assert_tag, but asserts that a matching tag does _not_
-      # exist. (See #assert_tag for a full discussion of the syntax.)
+      # Identical to +assert_tag+, but asserts that a matching tag does _not_
+      # exist. (See +assert_tag+ for a full discussion of the syntax.)
       #
       # === Examples
       #   # Assert that there is not a "div" containing a "p"
diff --git a/actionpack/lib/action_controller/base.rb b/actionpack/lib/action_controller/base.rb
index ea55fe42ce..a036600c2b 100755
--- a/actionpack/lib/action_controller/base.rb
+++ b/actionpack/lib/action_controller/base.rb
@@ -104,7 +104,7 @@ module ActionController #:nodoc:
   #   end
   #
   # Actions, by default, render a template in the <tt>app/views</tt> directory corresponding to the name of the controller and action
-  # after executing code in the action. For example, the +index+ action of the +GuestBookController+  would render the
+  # after executing code in the action. For example, the +index+ action of the GuestBookController would render the
   # template <tt>app/views/guestbook/index.erb</tt> by default after populating the <tt>@entries</tt> instance variable.
   #
   # Unlike index, the sign action will not render a template. After performing its main purpose (creating a
@@ -118,10 +118,10 @@ module ActionController #:nodoc:
   #
   # Requests are processed by the Action Controller framework by extracting the value of the "action" key in the request parameters.
   # This value should hold the name of the action to be performed. Once the action has been identified, the remaining
-  # request parameters, the session (if one is available), and the full request with all the http headers are made available to
+  # request parameters, the session (if one is available), and the full request with all the HTTP headers are made available to
   # the action through instance variables. Then the action is performed.
   #
-  # The full request object is available with the request accessor and is primarily used to query for http headers. These queries
+  # The full request object is available with the request accessor and is primarily used to query for HTTP headers. These queries
   # are made by accessing the environment hash, like this:
   #
   #   def server_ip
@@ -291,10 +291,10 @@ module ActionController #:nodoc:
     cattr_accessor :allow_concurrency
 
     # Modern REST web services often need to submit complex data to the web application.
-    # The param_parsers hash lets you register handlers which will process the http body and add parameters to the
-    # <tt>params</tt> hash. These handlers are invoked for post and put requests.
+    # The <tt>@@param_parsers</tt> hash lets you register handlers which will process the HTTP body and add parameters to the
+    # <tt>params</tt> hash. These handlers are invoked for POST and PUT requests.
     #
-    # By default application/xml is enabled. A XmlSimple class with the same param name as the root will be instantiated
+    # By default <tt>application/xml</tt> is enabled. A XmlSimple class with the same param name as the root will be instantiated
     # in the <tt>params</tt>. This allows XML requests to mask themselves as regular form submissions, so you can have one
     # action serve both regular forms and web service requests.
     #
@@ -307,7 +307,7 @@ module ActionController #:nodoc:
     #
     # Note: Up until release 1.1 of Rails, Action Controller would default to using XmlSimple configured to discard the
     # root node for such requests. The new default is to keep the root, such that "<r><name>David</name></r>" results
-    # in params[:r][:name] for "David" instead of params[:name]. To get the old behavior, you can
+    # in <tt>params[:r][:name]</tt> for "David" instead of <tt>params[:name]</tt>. To get the old behavior, you can
     # re-register XmlSimple as application/xml handler ike this:
     #
     #   ActionController::Base.param_parsers[Mime::XML] =
diff --git a/actionpack/lib/action_controller/cgi_ext/cookie.rb b/actionpack/lib/action_controller/cgi_ext/cookie.rb
index a244e2a39a..ef033fb4f3 100644
--- a/actionpack/lib/action_controller/cgi_ext/cookie.rb
+++ b/actionpack/lib/action_controller/cgi_ext/cookie.rb
@@ -6,25 +6,24 @@ class CGI #:nodoc:
     attr_accessor :name, :value, :path, :domain, :expires
     attr_reader :secure, :http_only
 
-    # Create a new CGI::Cookie object.
+    # Creates a new CGI::Cookie object.
     #
     # The contents of the cookie can be specified as a +name+ and one
     # or more +value+ arguments.  Alternatively, the contents can
     # be specified as a single hash argument.  The possible keywords of
     # this hash are as follows:
     #
-    # name:: the name of the cookie.  Required.
-    # value:: the cookie's value or list of values.
-    # path:: the path for which this cookie applies.  Defaults to the
-    #        base directory of the CGI script.
-    # domain:: the domain for which this cookie applies.
-    # expires:: the time at which this cookie expires, as a +Time+ object.
-    # secure:: whether this cookie is a secure cookie or not (default to
-    #          false).  Secure cookies are only transmitted to HTTPS
-    #          servers.
-    # http_only:: whether this cookie can be accessed by client side scripts (e.g. document.cookie) or only over HTTP 
-    #             More details: http://msdn2.microsoft.com/en-us/library/system.web.httpcookie.httponly.aspx
-    #             Defaults to false.
+    # * <tt>:name</tt> - The name of the cookie.  Required.
+    # * <tt>:value</tt> - The cookie's value or list of values.
+    # * <tt>:path</tt> - The path for which this cookie applies.  Defaults to the
+    #   base directory of the CGI script.
+    # * <tt>:domain</tt> - The domain for which this cookie applies.
+    # * <tt>:expires</tt> - The time at which this cookie expires, as a Time object.
+    # * <tt>:secure</tt> - Whether this cookie is a secure cookie or not (defaults to
+    #   +false+). Secure cookies are only transmitted to HTTPS servers.
+    # * <tt>:http_only</tt> - Whether this cookie can be accessed by client side scripts (e.g. document.cookie) or only over HTTP.
+    #   More details in http://msdn2.microsoft.com/en-us/library/system.web.httpcookie.httponly.aspx. Defaults to +false+. 
+    #
     # These keywords correspond to attributes of the cookie object.
     def initialize(name = '', *value)
       if name.kind_of?(String)
@@ -56,17 +55,17 @@ class CGI #:nodoc:
       super(@value)
     end
 
-    # Set whether the Cookie is a secure cookie or not.
+    # Sets whether the Cookie is a secure cookie or not.
     def secure=(val)
       @secure = val == true
     end
 
-    # Set whether the Cookie is an HTTP only cookie or not.
+    # Sets whether the Cookie is an HTTP only cookie or not.
     def http_only=(val)
       @http_only = val == true
     end
 
-    # Convert the Cookie to its string representation.
+    # Converts the Cookie to its string representation.
     def to_s
       buf = ''
       buf << @name << '='
@@ -79,11 +78,11 @@ class CGI #:nodoc:
       buf
     end
 
-    # Parse a raw cookie string into a hash of cookie-name=>Cookie
+    # Parses a raw cookie string into a hash of <tt>cookie-name => cookie-object</tt>
     # pairs.
     #
     #   cookies = CGI::Cookie::parse("raw_cookie_string")
-    #     # { "name1" => cookie1, "name2" => cookie2, ... }
+    #     # => { "name1" => cookie1, "name2" => cookie2, ... }
     #
     def self.parse(raw_cookie)
       cookies = Hash.new([])
diff --git a/actionpack/lib/action_controller/cgi_process.rb b/actionpack/lib/action_controller/cgi_process.rb
index 7e58c98bf2..8bc5e4c3a7 100644
--- a/actionpack/lib/action_controller/cgi_process.rb
+++ b/actionpack/lib/action_controller/cgi_process.rb
@@ -15,7 +15,7 @@ module ActionController #:nodoc:
     # * <tt>:new_session</tt> - if true, force creation of a new session.  If not set, a new session is only created if none currently
     #   exists.  If false, a new session is never created, and if none currently exists and the +session_id+ option is not set,
     #   an ArgumentError is raised.
-    # * <tt>:session_expires</tt> - the time the current session expires, as a +Time+ object.  If not set, the session will continue
+    # * <tt>:session_expires</tt> - the time the current session expires, as a Time object.  If not set, the session will continue
     #   indefinitely.
     # * <tt>:session_domain</tt> - the hostname domain for which this session is valid. If not set, defaults to the hostname of the
     #   server.
diff --git a/actionpack/lib/action_controller/filters.rb b/actionpack/lib/action_controller/filters.rb
index 6d0c83eb40..60d92d9b98 100644
--- a/actionpack/lib/action_controller/filters.rb
+++ b/actionpack/lib/action_controller/filters.rb
@@ -100,10 +100,10 @@ module ActionController #:nodoc:
     #
     # Around filters wrap an action, executing code both before and after.
     # They may be declared as method references, blocks, or objects responding
-    # to #filter or to both #before and #after.
+    # to +filter+ or to both +before+ and +after+.
     #
-    # To use a method as an around_filter, pass a symbol naming the Ruby method.
-    # Yield (or block.call) within the method to run the action.
+    # To use a method as an +around_filter+, pass a symbol naming the Ruby method.
+    # Yield (or <tt>block.call</tt>) within the method to run the action.
     #
     #   around_filter :catch_exceptions
     #
@@ -115,9 +115,9 @@ module ActionController #:nodoc:
     #       raise
     #     end
     #
-    # To use a block as an around_filter, pass a block taking as args both
+    # To use a block as an +around_filter+, pass a block taking as args both
     # the controller and the action block. You can't call yield directly from
-    # an around_filter block; explicitly call the action block instead:
+    # an +around_filter+ block; explicitly call the action block instead:
     #
     #   around_filter do |controller, action|
     #     logger.debug "before #{controller.action_name}"
@@ -125,7 +125,7 @@ module ActionController #:nodoc:
     #     logger.debug "after #{controller.action_name}"
     #   end
     #
-    # To use a filter object with around_filter, pass an object responding
+    # To use a filter object with +around_filter+, pass an object responding
     # to <tt>:filter</tt> or both <tt>:before</tt> and <tt>:after</tt>. With a
     # filter method, yield to the block as above:
     #
@@ -137,7 +137,7 @@ module ActionController #:nodoc:
     #     end
     #   end
     #
-    # With before and after methods:
+    # With +before+ and +after+ methods:
     #
     #   around_filter Authorizer.new
     #
@@ -154,9 +154,9 @@ module ActionController #:nodoc:
     #     end
     #   end
     #
-    # If the filter has before and after methods, the before method will be
-    # called before the action. If before renders or redirects, the filter chain is
-    # halted and after will not be run. See Filter Chain Halting below for
+    # If the filter has +before+ and +after+ methods, the +before+ method will be
+    # called before the action. If +before+ renders or redirects, the filter chain is
+    # halted and +after+ will not be run. See Filter Chain Halting below for
     # an example.
     #
     # == Filter chain skipping
@@ -215,7 +215,7 @@ module ActionController #:nodoc:
     #
     # <tt>before_filter</tt> and <tt>around_filter</tt> may halt the request
     # before a controller action is run. This is useful, for example, to deny
-    # access to unauthenticated users or to redirect from http to https.
+    # access to unauthenticated users or to redirect from HTTP to HTTPS.
     # Simply call render or redirect. After filters will not be executed if the filter 
     # chain is halted.
     #
@@ -241,10 +241,10 @@ module ActionController #:nodoc:
     #   . /
     #   #after (actual filter code is run, unless the around filter does not yield)
     #
-    # If #around returns before yielding, #after will still not be run. The #before
-    # filter and controller action will not be run. If #before renders or redirects,
-    # the second half of #around and will still run but #after and the
-    # action will not. If #around fails to yield, #after will not be run.
+    # If +around+ returns before yielding, +after+ will still not be run. The +before+
+    # filter and controller action will not be run. If +before+ renders or redirects,
+    # the second half of +around+ and will still run but +after+ and the
+    # action will not. If +around+ fails to yield, +after+ will not be run.
 
     class FilterChain < ActiveSupport::Callbacks::CallbackChain #:nodoc:
       def append_filter_to_chain(filters, filter_type, &block)
@@ -471,7 +471,7 @@ module ActionController #:nodoc:
       # Shorthand for append_after_filter since it's the most common.
       alias :after_filter :append_after_filter
 
-      # If you append_around_filter A.new, B.new, the filter chain looks like
+      # If you <tt>append_around_filter A.new, B.new</tt>, the filter chain looks like
       #
       #   B#before
       #     A#before
@@ -479,13 +479,13 @@ module ActionController #:nodoc:
       #     A#after
       #   B#after
       #
-      # With around filters which yield to the action block, #before and #after
+      # With around filters which yield to the action block, +before+ and +after+
       # are the code before and after the yield.
       def append_around_filter(*filters, &block)
         filter_chain.append_filter_to_chain(filters, :around, &block)
       end
 
-      # If you prepend_around_filter A.new, B.new, the filter chain looks like:
+      # If you <tt>prepend_around_filter A.new, B.new</tt>, the filter chain looks like:
       #
       #   A#before
       #     B#before
@@ -493,13 +493,13 @@ module ActionController #:nodoc:
       #     B#after
       #   A#after
       #
-      # With around filters which yield to the action block, #before and #after
+      # With around filters which yield to the action block, +before+ and +after+
       # are the code before and after the yield.
       def prepend_around_filter(*filters, &block)
         filter_chain.prepend_filter_to_chain(filters, :around, &block)
       end
 
-      # Shorthand for append_around_filter since it's the most common.
+      # Shorthand for +append_around_filter+ since it's the most common.
       alias :around_filter :append_around_filter
 
       # Removes the specified filters from the +before+ filter chain. Note that this only works for skipping method-reference
diff --git a/actionpack/lib/action_controller/helpers.rb b/actionpack/lib/action_controller/helpers.rb
index a8bead4d34..ce5e8be54c 100644
--- a/actionpack/lib/action_controller/helpers.rb
+++ b/actionpack/lib/action_controller/helpers.rb
@@ -20,7 +20,7 @@ module ActionController #:nodoc:
     end
 
     # The Rails framework provides a large number of helpers for working with +assets+, +dates+, +forms+, 
-    # +numbers+ and +ActiveRecord+ objects, to name a few. These helpers are available to all templates
+    # +numbers+ and Active Record 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
@@ -32,7 +32,7 @@ module ActionController #:nodoc:
     # 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 +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:
     #
     #   module FormattedTimeHelper
@@ -41,7 +41,7 @@ module ActionController #:nodoc:
     #     end
     #   end
     #
-    # +FormattedTimeHelper+ can now be included in a controller, using the +helper+ class method:
+    # FormattedTimeHelper can now be included in a controller, using the +helper+ class method:
     #
     #   class EventsController < ActionController::Base
     #     helper FormattedTimeHelper
@@ -74,22 +74,22 @@ module ActionController #:nodoc:
 
       # The +helper+ class method can take a series of helper module names, a block, or both.
       #
-      # * <tt>*args</tt>: One or more +Modules+, +Strings+ or +Symbols+, or the special symbol <tt>:all</tt>.
+      # * <tt>*args</tt>: One or more modules, strings or symbols, or the special symbol <tt>:all</tt>.
       # * <tt>&block</tt>: A block defining helper methods.
       # 
       # ==== Examples
-      # When the argument is a +String+ or +Symbol+, the method will provide the "_helper" suffix, require the file 
+      # When the argument is a string or symbol, the method will provide the "_helper" suffix, require the file 
       # and include the module in the template class.  The second form illustrates how to include custom helpers 
       # when working with namespaced controllers, or other cases where the file containing the helper definition is not
       # in one of Rails' standard load paths:
       #   helper :foo             # => requires 'foo_helper' and includes FooHelper
       #   helper 'resources/foo'  # => requires 'resources/foo_helper' and includes Resources::FooHelper
       #
-      # When the argument is a +Module+, it will be included directly in the template class.
+      # When the argument is a module it will be included directly in the template class.
       #   helper FooHelper # => includes FooHelper
       #
       # When the argument is the symbol <tt>:all</tt>, the controller will include all helpers from 
-      # <tt>app/helpers/**/*.rb</tt> under +RAILS_ROOT+.
+      # <tt>app/helpers/**/*.rb</tt> under RAILS_ROOT.
       #   helper :all
       #
       # Additionally, the +helper+ class method can receive and evaluate a block, making the methods defined available 
diff --git a/actionpack/lib/action_controller/integration.rb b/actionpack/lib/action_controller/integration.rb
index f0fc1945a9..bd69d02ed7 100644
--- a/actionpack/lib/action_controller/integration.rb
+++ b/actionpack/lib/action_controller/integration.rb
@@ -58,7 +58,7 @@ module ActionController
       class MultiPartNeededException < Exception
       end
 
-      # Create and initialize a new +Session+ instance.
+      # Create and initialize a new Session instance.
       def initialize
         reset!
       end
@@ -136,25 +136,25 @@ module ActionController
       end
 
       # Performs a GET request, following any subsequent redirect.
-      # See #request_via_redirect() for more information.
+      # See +request_via_redirect+ for more information.
       def get_via_redirect(path, parameters = nil, headers = nil)
         request_via_redirect(:get, path, parameters, headers)
       end
 
       # Performs a POST request, following any subsequent redirect.
-      # See #request_via_redirect() for more information.
+      # See +request_via_redirect+ for more information.
       def post_via_redirect(path, parameters = nil, headers = nil)
         request_via_redirect(:post, path, parameters, headers)
       end
 
       # Performs a PUT request, following any subsequent redirect.
-      # See #request_via_redirect() for more information.
+      # See +request_via_redirect+ for more information.
       def put_via_redirect(path, parameters = nil, headers = nil)
         request_via_redirect(:put, path, parameters, headers)
       end
 
       # Performs a DELETE request, following any subsequent redirect.
-      # See #request_via_redirect() for more information.
+      # See +request_via_redirect+ for more information.
       def delete_via_redirect(path, parameters = nil, headers = nil)
         request_via_redirect(:delete, path, parameters, headers)
       end
@@ -166,12 +166,12 @@ module ActionController
 
       # Performs a GET request with the given parameters. The parameters may
       # be +nil+, a Hash, or a string that is appropriately encoded
-      # (application/x-www-form-urlencoded or multipart/form-data).  The headers
-      # should be a hash.  The keys will automatically be upcased, with the
+      # (<tt>application/x-www-form-urlencoded</tt> or <tt>multipart/form-data</tt>).
+      # The headers should be a hash. The keys will automatically be upcased, with the
       # prefix 'HTTP_' added if needed.
       #
-      # You can also perform POST, PUT, DELETE, and HEAD requests with #post,
-      # #put, #delete, and #head.
+      # You can also perform POST, PUT, DELETE, and HEAD requests with +post+,
+      # +put+, +delete+, and +head+.
       def get(path, parameters = nil, headers = nil)
         process :get, path, parameters, headers
       end
diff --git a/actionpack/lib/action_controller/mime_type.rb b/actionpack/lib/action_controller/mime_type.rb
index f43e2ba06d..fa123f7808 100644
--- a/actionpack/lib/action_controller/mime_type.rb
+++ b/actionpack/lib/action_controller/mime_type.rb
@@ -104,7 +104,7 @@ module Mime
           list[text_xml].name = Mime::XML.to_s
         end
 
-        # Look for more specific xml-based types and sort them ahead of app/xml
+        # Look for more specific XML-based types and sort them ahead of app/xml
 
         if app_xml
           idx = app_xml
@@ -158,7 +158,7 @@ module Mime
       end
     end
 
-    # Returns true if ActionPack should check requests using this Mime Type for possible request forgery.  See
+    # Returns true if Action Pack should check requests using this Mime Type for possible request forgery.  See
     # ActionController::RequestForgerProtection.
     def verify_request?
       !@@unverifiable_types.include?(to_sym)
diff --git a/actionpack/lib/action_controller/polymorphic_routes.rb b/actionpack/lib/action_controller/polymorphic_routes.rb
index e2b7716aa2..509fa6a08e 100644
--- a/actionpack/lib/action_controller/polymorphic_routes.rb
+++ b/actionpack/lib/action_controller/polymorphic_routes.rb
@@ -1,6 +1,6 @@
 module ActionController
   # Polymorphic URL helpers are methods for smart resolution to a named route call when
-  # given an ActiveRecord model instance. They are to be used in combination with
+  # given an Active Record model instance. They are to be used in combination with
   # ActionController::Resources.
   #
   # These methods are useful when you want to generate correct URL or path to a RESTful
@@ -9,7 +9,9 @@ module ActionController
   # Nested resources and/or namespaces are also supported, as illustrated in the example:
   #
   #   polymorphic_url([:admin, @article, @comment])
-  #   #-> results in:
+  #
+  # results in:
+  #   
   #   admin_article_comment_url(@article, @comment)
   #
   # == Usage within the framework
@@ -38,11 +40,8 @@ module ActionController
   #
   # Example usage:
   #
-  #   edit_polymorphic_path(@post)
-  #   #=> /posts/1/edit
-  #
-  #   formatted_polymorphic_path([@post, :pdf])
-  #   #=> /posts/1.pdf
+  #   edit_polymorphic_path(@post)              # => "/posts/1/edit"
+  #   formatted_polymorphic_path([@post, :pdf]) # => "/posts/1.pdf"
   module PolymorphicRoutes
     # Constructs a call to a named RESTful route for the given record and returns the
     # resulting URL string. For example:
diff --git a/actionpack/lib/action_controller/resources.rb b/actionpack/lib/action_controller/resources.rb
index 26f75780c1..9fb1f9fa39 100644
--- a/actionpack/lib/action_controller/resources.rb
+++ b/actionpack/lib/action_controller/resources.rb
@@ -191,7 +191,7 @@ module ActionController
     #     end
     #   end
     #
-    # Along with the routes themselves, #resources generates named routes for use in
+    # Along with the routes themselves, +resources+ generates named routes for use in
     # controllers and views. <tt>map.resources :messages</tt> produces the following named routes and helpers:
     #
     #   Named Route   Helpers
@@ -208,7 +208,7 @@ module ActionController
     #   edit_message  edit_message_url(id), hash_for_edit_message_url(id),
     #                 edit_message_path(id), hash_for_edit_message_path(id)
     #
-    # You can use these helpers instead of #url_for or methods that take #url_for parameters. For example:
+    # You can use these helpers instead of +url_for+ or methods that take +url_for+ parameters. For example:
     #
     #   redirect_to :controller => 'messages', :action => 'index'
     #   # and
@@ -406,7 +406,7 @@ module ActionController
     #     end
     #   end
     #
-    # Along with the routes themselves, #resource generates named routes for
+    # Along with the routes themselves, +resource+ generates named routes for
     # use in controllers and views. <tt>map.resource :account</tt> produces
     # these named routes and helpers:
     #
diff --git a/actionpack/lib/action_controller/routing/builder.rb b/actionpack/lib/action_controller/routing/builder.rb
index b1a98d1a51..4740113ed0 100644
--- a/actionpack/lib/action_controller/routing/builder.rb
+++ b/actionpack/lib/action_controller/routing/builder.rb
@@ -23,9 +23,9 @@ module ActionController
       # Accepts a "route path" (a string defining a route), and returns the array
       # of segments that corresponds to it. Note that the segment array is only
       # partially initialized--the defaults and requirements, for instance, need
-      # to be set separately, via the #assign_route_options method, and the
-      # #optional? method for each segment will not be reliable until after
-      # #assign_route_options is called, as well.
+      # to be set separately, via the +assign_route_options+ method, and the
+      # <tt>optional?</tt> method for each segment will not be reliable until after
+      # +assign_route_options+ is called, as well.
       def segments_for_route_path(path)
         rest, segments = path, []
 
diff --git a/actionpack/lib/action_controller/session/cookie_store.rb b/actionpack/lib/action_controller/session/cookie_store.rb
index ada1862c3e..b477c1f7da 100644
--- a/actionpack/lib/action_controller/session/cookie_store.rb
+++ b/actionpack/lib/action_controller/session/cookie_store.rb
@@ -34,7 +34,7 @@ require 'openssl'       # to generate the HMAC message digest
 #   such as 'MD5', 'RIPEMD160', 'SHA256', etc.
 #
 # To generate a secret key for an existing application, run
-# `rake secret` and set the key in config/environment.rb.
+# "rake secret" and set the key in config/environment.rb.
 #
 # Note that changing digest or secret invalidates all existing sessions!
 class CGI::Session::CookieStore
diff --git a/actionpack/lib/action_controller/test_process.rb b/actionpack/lib/action_controller/test_process.rb
index f03ed5b2a7..0cf143210d 100644
--- a/actionpack/lib/action_controller/test_process.rb
+++ b/actionpack/lib/action_controller/test_process.rb
@@ -3,7 +3,7 @@ require 'action_controller/test_case'
 
 module ActionController #:nodoc:
   class Base
-    # Process a test request called with a +TestRequest+ object.
+    # Process a test request called with a TestRequest object.
     def self.process_test(request)
       new.process_test(request)
     end
@@ -358,7 +358,7 @@ module ActionController #:nodoc:
 
   module TestProcess
     def self.included(base)
-      # execute the request simulating a specific http method and set/volley the response
+      # execute the request simulating a specific HTTP method and set/volley the response
       %w( get post put delete head ).each do |method|
         base.class_eval <<-EOV, __FILE__, __LINE__
           def #{method}(action, parameters = nil, session = nil, flash = nil)
diff --git a/actionpack/lib/action_view/helpers/asset_tag_helper.rb b/actionpack/lib/action_view/helpers/asset_tag_helper.rb
index dfc7e2b3ed..e5a95a961c 100644
--- a/actionpack/lib/action_view/helpers/asset_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/asset_tag_helper.rb
@@ -11,8 +11,8 @@ module ActionView
     # === Using asset hosts
     # By default, Rails links to these assets on the current host in the public
     # folder, but you can direct Rails to link to assets from a dedicated assets server by 
-    # setting ActionController::Base.asset_host in your environment.rb.  For example,
-    # let's say your asset host is assets.example.com. 
+    # setting ActionController::Base.asset_host in your <tt>config/environment.rb</tt>.  For example,
+    # let's say your asset host is <tt>assets.example.com</tt>.
     #
     #   ActionController::Base.asset_host = "assets.example.com"
     #   image_tag("rails.png")
@@ -22,8 +22,8 @@ module ActionView
     #
     # This is useful since browsers typically open at most two connections to a single host,
     # which means your assets often wait in single file for their turn to load.  You can
-    # alleviate this by using a %d wildcard in <tt>asset_host</tt> (for example, "assets%d.example.com") 
-    # to automatically distribute asset requests among four hosts (e.g., assets0.example.com through assets3.example.com)
+    # alleviate this by using a <tt>%d</tt> wildcard in <tt>asset_host</tt> (for example, "assets%d.example.com") 
+    # to automatically distribute asset requests among four hosts (e.g., "assets0.example.com" through "assets3.example.com")
     # so browsers will open eight connections rather than two.  
     #
     #   image_tag("rails.png")
@@ -293,9 +293,9 @@ module ActionView
       end
 
       # Computes the path to a stylesheet asset in the public stylesheets directory.
-      # If the +source+ filename has no extension, .css will be appended.
+      # If the +source+ filename has no extension, <tt>.css</tt> will be appended.
       # Full paths from the document root will be passed through.
-      # Used internally by stylesheet_link_tag to build the stylesheet path.
+      # Used internally by +stylesheet_link_tag+ to build the stylesheet path.
       #
       # ==== Examples
       #   stylesheet_path "style" # => /stylesheets/style.css
@@ -309,7 +309,7 @@ module ActionView
       alias_method :path_to_stylesheet, :stylesheet_path # aliased to avoid conflicts with a stylesheet_path named route
 
       # Returns a stylesheet link tag for the sources specified as arguments. If
-      # you don't specify an extension, .css will be appended automatically.
+      # you don't specify an extension, <tt>.css</tt> will be appended automatically.
       # You can modify the link attributes by passing a hash as the last argument.
       #
       # ==== Examples
@@ -379,7 +379,7 @@ module ActionView
 
       # Computes the path to an image asset in the public images directory.
       # Full paths from the document root will be passed through.
-      # Used internally by image_tag to build the image path.
+      # Used internally by +image_tag+ to build the image path.
       #
       # ==== Examples
       #   image_path("edit")                                         # => /images/edit
@@ -454,8 +454,8 @@ module ActionView
           end
         end
 
-        # Add the .ext if not present. Return full URLs otherwise untouched.
-        # Prefix with /dir/ if lacking a leading /. Account for relative URL
+        # Add the the extension +ext+ if not present. Return full URLs otherwise untouched.
+        # Prefix with <tt>/dir/</tt> if lacking a leading +/+. Account for relative URL
         # roots. Rewrite the asset path for cache-busting asset ids. Include
         # asset host, if configured, with the correct request protocol.
         def compute_public_path(source, dir, ext = nil, include_host = true)
@@ -502,9 +502,9 @@ module ActionView
             end
         end
 
-        # Pick an asset host for this source. Returns nil if no host is set,
+        # Pick an asset host for this source. Returns +nil+ if no host is set,
         # the host if no wildcard is set, the host interpolated with the
-        # numbers 0-3 if it contains %d (the number is the source hash mod 4),
+        # numbers 0-3 if it contains <tt>%d</tt> (the number is the source hash mod 4),
         # or the value returned from invoking the proc if it's a proc.
         def compute_asset_host(source)
           if host = ActionController::Base.asset_host
diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb
index 0962be2c79..0791feb9ac 100644
--- a/actionpack/lib/action_view/helpers/form_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_helper.rb
@@ -86,15 +86,15 @@ module ActionView
       #     <%= f.text_field :author %><br />
       #   <% end %>
       #
-      # There, +form_for+ is able to generate the rest of RESTful parameters
+      # There, +form_for+ is able to generate the rest of RESTful form parameters
       # based on introspection on the record, but to understand what it does we
       # need to dig first into the alternative generic usage it is based upon.
       #
       # === Generic form_for
       #
-      # The generic way to call +form_for+ requires a few arguments:
+      # The generic way to call +form_for+ yields a form builder around a model:
       #
-      #   <% form_for :person, @person, :url => { :action => "update" } do |f| %>
+      #   <% form_for :person, :url => { :action => "update" } do |f| %>
       #     <%= f.error_messages %>
       #     First name: <%= f.text_field :first_name %><br />
       #     Last name : <%= f.text_field :last_name %><br />
@@ -102,21 +102,48 @@ module ActionView
       #     Admin?    : <%= f.check_box :admin %><br />
       #   <% end %>
       #
+      # There, the first argument is a symbol or string with the name of the
+      # object the form is about, and also the name of the instance variable the
+      # object is stored in.
+      #
+      # The form builder acts as a regular form helper that somehow carries the
+      # model. Thus, the idea is that
+      #
+      #   <%= f.text_field :first_name %>
+      #
+      # gets expanded to
+      #
+      #   <%= text_field :person, :first_name %>
+      #
+      # If the instance variable is not <tt>@person</tt> you can pass the actual
+      # record as the second argument:
+      #
+      #   <% form_for :person, person, :url => { :action => "update" } do |f| %>
+      #     ...
+      #   <% end %>
+      #
+      # In that case you can think
+      #
+      #   <%= f.text_field :first_name %>
+      #
+      # gets expanded to
+      #
+      #   <%= text_field :person, :first_name, :object => person %>
+      #
+      # You can even display error messages of the wrapped model this way:
+      #
+      #   <%= f.error_messages %>
+      #
+      # In any of its variants, the rightmost argument to +form_for+ is an
+      # optional hash of options:
+      #
+      # * <tt>:url</tt> - The URL the form is submitted to. It takes the same fields
+      #   you pass to +url_for+ or +link_to+. In particular you may pass here a
+      #   named route directly as well. Defaults to the current action.
+      # * <tt>:html</tt> - Optional HTML attributes for the form tag.
+      #
       # Worth noting is that the +form_for+ tag is called in a ERb evaluation block,
-      # not an ERb output block. So that's <tt><% %></tt>, not <tt><%= %></tt>. Also
-      # worth noting is that +form_for+ yields a form builder object, in this
-      # example as +f+, which emulates the API for the stand-alone FormHelper
-      # methods, but without the object name. So instead of <tt>text_field :person, :name</tt>,
-      # you get away with <tt>f.text_field :name</tt>. Notice that you can even do
-      # <tt><%= f.error_messages %></tt> to display the error messsages of the model
-      # object in question.
-      #
-      # Even further, the +form_for+ method allows you to more easily escape the
-      # instance variable convention. So while the stand-alone approach would require
-      # <tt>text_field :person, :name, :object => person</tt> to work with local
-      # variables instead of instance ones, the +form_for+ calls remain the same.
-      # You simply declare once with <tt>:person, person</tt> and all subsequent
-      # field calls save <tt>:person</tt> and <tt>:object => person</tt>.
+      # not an ERb output block. So that's <tt><% %></tt>, not <tt><%= %></tt>.
       #
       # Also note that +form_for+ doesn't create an exclusive scope. It's still
       # possible to use both the stand-alone FormHelper methods and methods from
@@ -133,40 +160,32 @@ module ActionView
       # designed to work with an object as base, like FormOptionHelper#collection_select
       # and DateHelper#datetime_select.
       #
-      # HTML attributes for the form tag can be given as <tt>:html => {...}</tt>.
-      # For example:
-      #
-      #   <% form_for :person, @person, :html => {:id => 'person_form'} do |f| %>
-      #     ...
-      #   <% end %>
-      #
-      # The above form will then have the +id+ attribute with the value "person_form",
-      # which you can then style with CSS or manipulate with JavaScript.
-      #
-      # === Relying on record identification
+      # === Resource-oriented style
       #
       # As we said above, in addition to manually configuring the +form_for+ call,
-      # you can rely on record identification, which will use the conventions and
-      # named routes of that approach. This is the preferred way to use +form_for+
-      # nowadays:
+      # you can rely on automated resource identification, which will use the conventions
+      # and named routes of that approach. This is the preferred way to use +form_for+
+      # nowadays.
+      #
+      # For example, if <tt>@post</tt> is an existing record you want to edit
       #
-      #   <% form_for(@post) do |f| %>
+      #   <% form_for @post do |f| %>
       #     ...
       #   <% end %>
       #
-      # This will expand to be the same as:
+      # is equivalent to something like:
       #
       #   <% form_for :post, @post, :url => post_path(@post), :html => { :method => :put, :class => "edit_post", :id => "edit_post_45" } do |f| %>
       #     ...
       #   <% end %>
       #
-      # And for new records:
+      # And for new records
       #
       #   <% form_for(Post.new) do |f| %>
       #     ...
       #   <% end %>
       #
-      # This will expand to be the same as:
+      # expands to
       #
       #   <% form_for :post, Post.new, :url => posts_path, :html => { :class => "new_post", :id => "new_post" } do |f| %>
       #     ...
@@ -305,13 +324,13 @@ module ActionView
       #
       # ==== Examples
       #   label(:post, :title)
-      #   #=> <label for="post_title">Title</label>
+      #   # => <label for="post_title">Title</label>
       #
       #   label(:post, :title, "A short title")
-      #   #=> <label for="post_title">A short title</label>
+      #   # => <label for="post_title">A short title</label>
       #
       #   label(:post, :title, "A short title", :class => "title_label")
-      #   #=> <label for="post_title" class="title_label">A short title</label>
+      #   # => <label for="post_title" class="title_label">A short title</label>
       #
       def label(object_name, method, text = nil, options = {})
         InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_label_tag(text, options)
diff --git a/actionpack/lib/action_view/helpers/form_options_helper.rb b/actionpack/lib/action_view/helpers/form_options_helper.rb
index 6f3818659e..e0a097e367 100644
--- a/actionpack/lib/action_view/helpers/form_options_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_options_helper.rb
@@ -119,7 +119,7 @@ module ActionView
       #     end
       #   end
       #
-      # Sample usage (selecting the associated +Author+ for an instance of +Post+, <tt>@post</tt>):
+      # Sample usage (selecting the associated Author for an instance of Post, <tt>@post</tt>):
       #   collection_select(:post, :author_id, Author.find(:all), :id, :name_with_initial, {:prompt => true})
       #
       # If <tt>@post.author_id</tt> is already <tt>1</tt>, this would return:
@@ -144,7 +144,7 @@ module ActionView
       # In addition to the <tt>:include_blank</tt> option documented above,
       # this method also supports a <tt>:model</tt> option, which defaults
       # to TimeZone. This may be used by users to specify a different time
-      # zone model object. (See #time_zone_options_for_select for more
+      # zone model object. (See +time_zone_options_for_select+ for more
       # information.)
       #
       # You can also supply an array of TimeZone objects
@@ -153,7 +153,7 @@ module ActionView
       # obtaining a list of the US time zones.)
       #
       # Finally, this method supports a <tt>:default</tt> option, which selects
-      # a default TimeZone if the object's time zone is nil.
+      # a default TimeZone if the object's time zone is +nil+.
       #
       # Examples:
       #   time_zone_select( "user", "time_zone", nil, :include_blank => true)
@@ -172,7 +172,7 @@ module ActionView
       # Accepts a container (hash, array, enumerable, your type) and returns a string of option tags. Given a container
       # where the elements respond to first and last (such as a two-element array), the "lasts" serve as option values and
       # the "firsts" as option text. Hashes are turned into this form automatically, so the keys become "firsts" and values
-      # become lasts. If +selected+ is specified, the matching "last" or element will get the selected option-tag.  +Selected+
+      # become lasts. If +selected+ is specified, the matching "last" or element will get the selected option-tag.  +selected+
       # may also be an array of values to be selected when using a multiple select.
       #
       # Examples (call, result):
@@ -217,24 +217,22 @@ module ActionView
         options_for_select(options, selected)
       end
 
-      # Returns a string of <tt><option></tt> tags, like <tt>#options_from_collection_for_select</tt>, but
+      # Returns a string of <tt><option></tt> tags, like <tt>options_from_collection_for_select</tt>, but
       # groups them by <tt><optgroup></tt> tags based on the object relationships of the arguments.
       #
       # Parameters:
-      # +collection+::          An array of objects representing the <tt><optgroup></tt> tags
-      # +group_method+::        The name of a method which, when called on a member of +collection+, returns an
-      #                         array of child objects representing the <tt><option></tt> tags
-      # +group_label_method+::  The name of a method which, when called on a member of +collection+, returns a
-      #                         string to be used as the +label+ attribute for its <tt><optgroup></tt> tag
-      # +option_key_method+::   The name of a method which, when called on a child object of a member of
-      #                         +collection+, returns a value to be used as the +value+ attribute for its
-      #                         <tt><option></tt> tag
-      # +option_value_method+:: The name of a method which, when called on a child object of a member of
-      #                         +collection+, returns a value to be used as the contents of its
-      #                         <tt><option></tt> tag
-      # +selected_key+::        A value equal to the +value+ attribute for one of the <tt><option></tt> tags,
-      #                         which will have the +selected+ attribute set. Corresponds to the return value
-      #                         of one of the calls to +option_key_method+. If +nil+, no selection is made.
+      # * +collection+ - An array of objects representing the <tt><optgroup></tt> tags.
+      # * +group_method+ - The name of a method which, when called on a member of +collection+, returns an
+      #   array of child objects representing the <tt><option></tt> tags.
+      # * group_label_method+ - The name of a method which, when called on a member of +collection+, returns a
+      #   string to be used as the +label+ attribute for its <tt><optgroup></tt> tag.
+      # * +option_key_method+ - The name of a method which, when called on a child object of a member of
+      #   +collection+, returns a value to be used as the +value+ attribute for its <tt><option></tt> tag.
+      # * +option_value_method+ - The name of a method which, when called on a child object of a member of
+      #   +collection+, returns a value to be used as the contents of its <tt><option></tt> tag.
+      # * +selected_key+ - A value equal to the +value+ attribute for one of the <tt><option></tt> tags,
+      #   which will have the +selected+ attribute set. Corresponds to the return value of one of the calls
+      #   to +option_key_method+. If +nil+, no selection is made.
       #
       # Example object structure for use with this method:
       #   class Continent < ActiveRecord::Base
@@ -300,8 +298,8 @@ module ActionView
       # a TimeZone.
       #
       # By default, +model+ is the TimeZone constant (which can be obtained
-      # in ActiveRecord as a value object). The only requirement is that the
-      # +model+ parameter be an object that responds to #all, and returns
+      # in Active Record as a value object). The only requirement is that the
+      # +model+ parameter be an object that responds to +all+, and returns
       # an array of objects that represent time zones.
       #
       # NOTE: Only the option tags are returned, you have to wrap this call in
diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb
index 922a0662fe..ca58f4ba26 100644
--- a/actionpack/lib/action_view/helpers/form_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb
@@ -3,7 +3,7 @@ require 'action_view/helpers/tag_helper'
 
 module ActionView
   module Helpers
-    # Provides a number of methods for creating form tags that doesn't rely on an ActiveRecord object assigned to the template like
+    # Provides a number of methods for creating form tags that doesn't rely on an Active Record object assigned to the template like
     # FormHelper does. Instead, you provide the names and values manually.
     #
     # NOTE: The HTML options <tt>disabled</tt>, <tt>readonly</tt>, and <tt>multiple</tt> can all be treated as booleans. So specifying 
@@ -14,9 +14,9 @@ module ActionView
       #
       # ==== Options
       # * <tt>:multipart</tt> - If set to true, the enctype is set to "multipart/form-data".
-      # * <tt>:method</tt>    - The method to use when submitting the form, usually either "get" or "post".
-      #                         If "put", "delete", or another verb is used, a hidden input with name _method 
-      #                         is added to simulate the verb over post.
+      # * <tt>:method</tt> - The method to use when submitting the form, usually either "get" or "post".
+      #   If "put", "delete", or another verb is used, a hidden input with name <tt>_method</tt>
+      #   is added to simulate the verb over post.
       # * A list of parameters to feed to the URL the form will be posted to.
       #
       # ==== Examples
diff --git a/actionpack/lib/action_view/helpers/prototype_helper.rb b/actionpack/lib/action_view/helpers/prototype_helper.rb
index 04bf5f2a30..602832e470 100644
--- a/actionpack/lib/action_view/helpers/prototype_helper.rb
+++ b/actionpack/lib/action_view/helpers/prototype_helper.rb
@@ -595,8 +595,8 @@ module ActionView
         # JavaScript sent with a Content-type of "text/javascript".
         #
         # Create new instances with PrototypeHelper#update_page or with 
-        # ActionController::Base#render, then call #insert_html, #replace_html, 
-        # #remove, #show, #hide, #visual_effect, or any other of the built-in 
+        # ActionController::Base#render, then call +insert_html+, +replace_html+, 
+        # +remove+, +show+, +hide+, +visual_effect+, or any other of the built-in 
         # methods on the yielded generator in any order you like to modify the 
         # content and appearance of the current page. 
         #
@@ -687,7 +687,7 @@ module ActionView
             end
           end
           
-          # Returns an object whose <tt>#to_json</tt> evaluates to +code+. Use this to pass a literal JavaScript 
+          # Returns an object whose <tt>to_json</tt> evaluates to +code+. Use this to pass a literal JavaScript 
           # expression as an argument to another JavaScriptGenerator method.
           def literal(code)
             ActiveSupport::JSON::Variable.new(code.to_s)
@@ -1173,7 +1173,7 @@ module ActionView
         super(generator)
       end
 
-      # The JSON Encoder calls this to check for the #to_json method
+      # The JSON Encoder calls this to check for the +to_json+ method
       # Since it's a blank slate object, I suppose it responds to anything.
       def respond_to?(method)
         true
diff --git a/actionpack/lib/action_view/helpers/record_tag_helper.rb b/actionpack/lib/action_view/helpers/record_tag_helper.rb
index 40b66be79f..66c596f3a9 100644
--- a/actionpack/lib/action_view/helpers/record_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/record_tag_helper.rb
@@ -2,7 +2,7 @@ module ActionView
   module Helpers
     module RecordTagHelper
       # Produces a wrapper DIV element with id and class parameters that
-      # relate to the specified ActiveRecord object. Usage example:
+      # relate to the specified Active Record object. Usage example:
       #
       #    <% div_for(@person, :class => "foo") do %>
       #       <%=h @person.name %>
@@ -17,7 +17,7 @@ module ActionView
       end
   
       # content_tag_for creates an HTML element with id and class parameters
-      # that relate to the specified ActiveRecord object. For example:
+      # that relate to the specified Active Record object. For example:
       #
       #    <% content_tag_for(:tr, @person) do %>
       #      <td><%=h @person.first_name %></td>
diff --git a/actionpack/lib/action_view/helpers/sanitize_helper.rb b/actionpack/lib/action_view/helpers/sanitize_helper.rb
index 6c0a7ec25c..b0dacfe964 100644
--- a/actionpack/lib/action_view/helpers/sanitize_helper.rb
+++ b/actionpack/lib/action_view/helpers/sanitize_helper.rb
@@ -57,7 +57,7 @@ module ActionView
         self.class.white_list_sanitizer.sanitize(html, options)
       end
 
-      # Sanitizes a block of css code.  Used by #sanitize when it comes across a style attribute
+      # Sanitizes a block of CSS code. Used by +sanitize+ when it comes across a style attribute.
       def sanitize_css(style)
         self.class.white_list_sanitizer.sanitize_css(style)
       end
@@ -111,8 +111,8 @@ module ActionView
           end
         end
         
-        # Gets the HTML::FullSanitizer instance used by strip_tags.  Replace with
-        # any object that responds to #sanitize
+        # Gets the HTML::FullSanitizer instance used by +strip_tags+.  Replace with
+        # any object that responds to +sanitize+.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.full_sanitizer = MySpecialSanitizer.new
@@ -122,8 +122,8 @@ module ActionView
           @full_sanitizer ||= HTML::FullSanitizer.new
         end
 
-        # Gets the HTML::LinkSanitizer instance used by strip_links.  Replace with
-        # any object that responds to #sanitize
+        # Gets the HTML::LinkSanitizer instance used by +strip_links+.  Replace with
+        # any object that responds to +sanitize+.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.link_sanitizer = MySpecialSanitizer.new
@@ -133,8 +133,8 @@ module ActionView
           @link_sanitizer ||= HTML::LinkSanitizer.new
         end
 
-        # Gets the HTML::WhiteListSanitizer instance used by sanitize and sanitize_css.
-        # Replace with any object that responds to #sanitize
+        # Gets the HTML::WhiteListSanitizer instance used by sanitize and +sanitize_css+.
+        # Replace with any object that responds to +sanitize+.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.white_list_sanitizer = MySpecialSanitizer.new
@@ -144,7 +144,7 @@ module ActionView
           @white_list_sanitizer ||= HTML::WhiteListSanitizer.new
         end
 
-        # Adds valid HTML attributes that the #sanitize helper checks for URIs.
+        # Adds valid HTML attributes that the +sanitize+ helper checks for URIs.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_uri_attributes = 'lowsrc', 'target'
@@ -154,7 +154,7 @@ module ActionView
           HTML::WhiteListSanitizer.uri_attributes.merge(attributes)
         end
 
-        # Adds to the Set of 'bad' tags for the #sanitize helper.
+        # Adds to the Set of 'bad' tags for the +sanitize+ helper.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_bad_tags = 'embed', 'object'
@@ -163,7 +163,8 @@ module ActionView
         def sanitized_bad_tags=(attributes)
           HTML::WhiteListSanitizer.bad_tags.merge(attributes)
         end
-        # Adds to the Set of allowed tags for the #sanitize helper.
+
+        # Adds to the Set of allowed tags for the +sanitize+ helper.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_allowed_tags = 'table', 'tr', 'td'
@@ -173,7 +174,7 @@ module ActionView
           HTML::WhiteListSanitizer.allowed_tags.merge(attributes)
         end
 
-        # Adds to the Set of allowed html attributes for the #sanitize helper.
+        # Adds to the Set of allowed HTML attributes for the +sanitize+ helper.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_allowed_attributes = 'onclick', 'longdesc'
@@ -183,7 +184,7 @@ module ActionView
           HTML::WhiteListSanitizer.allowed_attributes.merge(attributes)
         end
 
-        # Adds to the Set of allowed css properties for the #sanitize and #sanitize_css heleprs.
+        # Adds to the Set of allowed CSS properties for the #sanitize and +sanitize_css+ heleprs.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_allowed_css_properties = 'expression'
@@ -193,7 +194,7 @@ module ActionView
           HTML::WhiteListSanitizer.allowed_css_properties.merge(attributes)
         end
 
-        # Adds to the Set of allowed css keywords for the #sanitize and #sanitize_css helpers.
+        # Adds to the Set of allowed CSS keywords for the +sanitize+ and +sanitize_css+ helpers.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_allowed_css_keywords = 'expression'
@@ -203,7 +204,7 @@ module ActionView
           HTML::WhiteListSanitizer.allowed_css_keywords.merge(attributes)
         end
 
-        # Adds to the Set of allowed shorthand css properties for the #sanitize and #sanitize_css helpers.
+        # Adds to the Set of allowed shorthand CSS properties for the +sanitize+ and +sanitize_css+ helpers.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_shorthand_css_properties = 'expression'
@@ -213,7 +214,7 @@ module ActionView
           HTML::WhiteListSanitizer.shorthand_css_properties.merge(attributes)
         end
 
-        # Adds to the Set of allowed protocols for the #sanitize helper.
+        # Adds to the Set of allowed protocols for the +sanitize+ helper.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_allowed_protocols = 'ssh', 'feed'
diff --git a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
index 12b4cfd3f8..c9b2761cb8 100644
--- a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
+++ b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
@@ -26,9 +26,9 @@ module ActionView
       #         :url => { :action => "reload" }, 
       #         :complete => visual_effect(:highlight, "posts", :duration => 0.5)
       #
-      # If no element_id is given, it assumes "element" which should be a local
+      # If no +element_id+ is given, it assumes "element" which should be a local
       # variable in the generated JavaScript execution context. This can be 
-      # used for example with drop_receiving_element:
+      # used for example with +drop_receiving_element+:
       #
       #   <%= drop_receiving_element (...), :loading => visual_effect(:fade) %>
       #
@@ -67,6 +67,7 @@ module ActionView
       # element as parameters.
       #
       # Example:
+      #
       #   <%= sortable_element("my_list", :url => { :action => "order" }) %>
       #
       # In the example, the action gets a "my_list" array parameter 
@@ -79,60 +80,56 @@ module ActionView
       # 
       # Additional +options+ are:
       #
-      # <tt>:format</tt>::               A regular expression to determine what to send
-      #                                  as the serialized id to the server (the default
-      #                                  is <tt>/^[^_]*_(.*)$/</tt>).
-      #                                  
-      # <tt>:constraint</tt>::           Whether to constrain the dragging to either <tt>:horizontal</tt>
-      #                                  or <tt>:vertical</tt> (or false to make it unconstrained).
-      #                                   
-      # <tt>:overlap</tt>::              Calculate the item overlap in the <tt>:horizontal</tt> or 
-      #                                  <tt>:vertical</tt> direction.
-      #                                   
-      # <tt>:tag</tt>::                  Which children of the container element to treat as
-      #                                  sortable (default is <tt>li</tt>).
-      #                                  
-      # <tt>:containment</tt>::          Takes an element or array of elements to treat as
-      #                                  potential drop targets (defaults to the original
-      #                                  target element).
-      #                                  
-      # <tt>:only</tt>::                 A CSS class name or arry of class names used to filter
-      #                                  out child elements as candidates.
-      #                                  
-      # <tt>:scroll</tt>::               Determines whether to scroll the list during drag
-      #                                  operations if the list runs past the visual border.
-      #                                  
-      # <tt>:tree</tt>::                 Determines whether to treat nested lists as part of the
-      #                                  main sortable list. This means that you can create multi-
-      #                                  layer lists, and not only sort items at the same level,
-      #                                  but drag and sort items between levels.
-      #                                  
-      # <tt>:hoverclass</tt>::           If set, the Droppable will have this additional CSS class
-      #                                  when an accepted Draggable is hovered over it.                         
-      #                                 
-      # <tt>:handle</tt>::               Sets whether the element should only be draggable by an
-      #                                  embedded handle. The value may be a string referencing a
-      #                                  CSS class value (as of script.aculo.us V1.5). The first
-      #                                  child/grandchild/etc. element found within the element
-      #                                  that has this CSS class value will be used as the handle.
-      #
-      # <tt>:ghosting</tt>::             Clones the element and drags the clone, leaving the original
-      #                                  in place until the clone is dropped (default is <tt>false</tt>).
-      #       
-      # <tt>:dropOnEmpty</tt>::          If set to true, the Sortable container will be made into
-      #                                  a Droppable, that can receive a Draggable (as according to
-      #                                  the containment rules) as a child element when there are no
-      #                                  more elements inside (default is <tt>false</tt>).
-      #       
-      # <tt>:onChange</tt>::             Called whenever the sort order changes while dragging. When
-      #                                  dragging from one Sortable to another, the callback is
-      #                                  called once on each Sortable. Gets the affected element as
-      #                                  its parameter.
-      #                                 
-      # <tt>:onUpdate</tt>::             Called when the drag ends and the Sortable's order is
-      #                                  changed in any way. When dragging from one Sortable to
-      #                                  another, the callback is called once on each Sortable. Gets
-      #                                  the container as its parameter.
+      # * <tt>:format</tt> - A regular expression to determine what to send as the
+      #   serialized id to the server (the default is <tt>/^[^_]*_(.*)$/</tt>).
+      #                           
+      # * <tt>:constraint</tt> - Whether to constrain the dragging to either
+      #   <tt>:horizontal</tt> or <tt>:vertical</tt> (or false to make it unconstrained).
+      #                            
+      # * <tt>:overlap</tt> - Calculate the item overlap in the <tt>:horizontal</tt>
+      #   or <tt>:vertical</tt> direction.
+      #                            
+      # * <tt>:tag</tt> - Which children of the container element to treat as
+      #   sortable (default is <tt>li</tt>).
+      #                          
+      # * <tt>:containment</tt> - Takes an element or array of elements to treat as
+      #   potential drop targets (defaults to the original target element).
+      #                          
+      # * <tt>:only</tt> - A CSS class name or arry of class names used to filter
+      #   out child elements as candidates.
+      #                          
+      # * <tt>:scroll</tt> - Determines whether to scroll the list during drag
+      #   operations if the list runs past the visual border.
+      #                          
+      # * <tt>:tree</tt> - Determines whether to treat nested lists as part of the
+      #   main sortable list. This means that you can create multi-layer lists,
+      #   and not only sort items at the same level, but drag and sort items
+      #   between levels.
+      #                          
+      # * <tt>:hoverclass</tt> - If set, the Droppable will have this additional CSS class
+      #   when an accepted Draggable is hovered over it.                         
+      #                          
+      # * <tt>:handle</tt> - Sets whether the element should only be draggable by an
+      #   embedded handle. The value may be a string referencing a CSS class value
+      #   (as of script.aculo.us V1.5). The first child/grandchild/etc. element
+      #   found within the element that has this CSS class value will be used as
+      #   the handle.
+      #                          
+      # * <tt>:ghosting</tt> - Clones the element and drags the clone, leaving
+      #   the original in place until the clone is dropped (default is <tt>false</tt>).
+      #                          
+      # * <tt>:dropOnEmpty</tt> - If true the Sortable container will be made into
+      #   a Droppable, that can receive a Draggable (as according to the containment
+      #   rules) as a child element when there are no more elements inside (default
+      #   is <tt>false</tt>).
+      #                          
+      # * <tt>:onChange</tt> - Called whenever the sort order changes while dragging. When
+      #   dragging from one Sortable to another, the callback is called once on each
+      #   Sortable. Gets the affected element as its parameter.
+      #                          
+      # * <tt>:onUpdate</tt> - Called when the drag ends and the Sortable's order is
+      #   changed in any way. When dragging from one Sortable to another, the callback
+      #   is called once on each Sortable. Gets the container as its parameter.
       #                                                                                         
       # See http://script.aculo.us for more documentation.
       def sortable_element(element_id, options = {})
@@ -170,8 +167,8 @@ module ActionView
       end
 
       # Makes the element with the DOM ID specified by +element_id+ receive
-      # dropped draggable elements (created by draggable_element).
-      # and make an AJAX call  By default, the action called gets the DOM ID 
+      # dropped draggable elements (created by +draggable_element+).
+      # and make an AJAX call. By default, the action called gets the DOM ID 
       # of the element as parameter.
       #
       # Example:
@@ -182,32 +179,30 @@ module ActionView
       # http://script.aculo.us for more documentation.
       #
       # Some of these +options+ include:
-      # <tt>:accept</tt>::               Set this to a string or an array of strings describing the
-      #                                  allowable CSS classes that the draggable_element must have in order 
-      #                                  to be accepted by this drop_receiving_element.
-      #
-      # <tt>:confirm</tt>::              Adds a confirmation dialog.
-      #                                 
-      #                                  Example:
-      #                                    :confirm => "Are you sure you want to do this?"
-      #                                 
-      # <tt>:hoverclass</tt>::           If set, the drop_receiving_element will have this additional CSS class
-      #                                  when an accepted draggable_element is hovered over it.                         
-      #                                  
-      # <tt>:onDrop</tt>::               Called when a draggable_element is dropped onto this element.  
-      #                                  Override this callback with a javascript expression to 
-      #                                  change the default drop behavour.
-      #                                 
-      #                                  Example:
-      #                                    :onDrop => "function(draggable_element, droppable_element, event) { alert('I like bananas') }"
-      #                          
-      #                                  This callback gets three parameters:      
-      #                                  The +Draggable+ element, the +Droppable+ element and the 
-      #                                  +Event+ object.  You can extract additional information about the 
-      #                                  drop - like if the Ctrl or Shift keys were pressed - from the +Event+ object.
-      #
-      # <tt>:with</tt>::                 A JavaScript expression specifying the parameters for the XMLHttpRequest.
-      #                                  Any expressions should return a valid URL query string.
+      # * <tt>:accept</tt> - Set this to a string or an array of strings describing the
+      #   allowable CSS classes that the +draggable_element+ must have in order 
+      #   to be accepted by this +drop_receiving_element+.
+      #                          
+      # * <tt>:confirm</tt> - Adds a confirmation dialog. Example:
+      #                     
+      #     :confirm => "Are you sure you want to do this?"
+      #                          
+      # * <tt>:hoverclass</tt> - If set, the +drop_receiving_element+ will have
+      #   this additional CSS class when an accepted +draggable_element+ is
+      #   hovered over it.                         
+      #                          
+      # * <tt>:onDrop</tt> - Called when a +draggable_element+ is dropped onto
+      #   this element. Override this callback with a JavaScript expression to 
+      #   change the default drop behavour. Example:
+      #                          
+      #     :onDrop => "function(draggable_element, droppable_element, event) { alert('I like bananas') }"
+      #                          
+      #   This callback gets three parameters: The Draggable element, the Droppable
+      #   element and the Event object. You can extract additional information about
+      #   the drop - like if the Ctrl or Shift keys were pressed - from the Event object.
+      #                          
+      # * <tt>:with</tt> - A JavaScript expression specifying the parameters for
+      #   the XMLHttpRequest. Any expressions should return a valid URL query string.
       def drop_receiving_element(element_id, options = {})
         javascript_tag(drop_receiving_element_js(element_id, options).chop!)
       end
diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb
index 38c8d18cb0..4b12adf225 100644
--- a/actionpack/lib/action_view/helpers/url_helper.rb
+++ b/actionpack/lib/action_view/helpers/url_helper.rb
@@ -10,7 +10,7 @@ module ActionView
       include JavaScriptHelper
 
       # Returns the URL for the set of +options+ provided. This takes the
-      # same options as url_for in ActionController (see the
+      # same options as +url_for+ in Action Controller (see the
       # documentation for ActionController::Base#url_for). Note that by default
       # <tt>:only_path</tt> is <tt>true</tt> so you'll get the relative /controller/action
       # instead of the fully qualified URL like http://example.com/controller/action.
diff --git a/actionpack/lib/action_view/template.rb b/actionpack/lib/action_view/template.rb
index 2cda3d94b5..369526188f 100644
--- a/actionpack/lib/action_view/template.rb
+++ b/actionpack/lib/action_view/template.rb
@@ -93,9 +93,9 @@ module ActionView #:nodoc:
     # Register a class that knows how to handle template files with the given
     # extension. This can be used to implement new template types.
     # The constructor for the class must take the ActiveView::Base instance
-    # as a parameter, and the class must implement a #render method that
+    # as a parameter, and the class must implement a +render+ method that
     # takes the contents of the template to render as well as the Hash of
-    # local assigns available to the template. The #render method ought to
+    # local assigns available to the template. The +render+ method ought to
     # return the rendered template as a string.
     def self.register_template_handler(extension, klass)
       @@template_handlers[extension.to_sym] = klass