Merge docrails:

commit e6afd8b2736364322b673bbdcca3e9b38b6d3da0
Author: Xavier Noria <fxn@hashref.com>
Date:   Thu May 8 23:49:36 2008 +0200

    Overall documentation improvement and markup corrections. Zillion changes.

commit 2fead68b3192332eee27945ed95a94a64ca73f70
Author: Austin Putman <austin@emmanuel.local>
Date:   Wed May 7 19:35:46 2008 -0700

    Documented class methods on ActionController::Routing.  These are dangerous, and mostly used for testing.

commit f5b84182dbc39bea79c8ee319c688d00fa99f9d1
Author: Teflon Ted <github@rudiment.net>
Date:   Wed May 7 16:08:49 2008 -0400

    Added explanation about errant inflections not being patched in the future in order to avoid breaking legacy applications.

commit 370f4f51722cec49ace17093d29e9ce9e8f15cfb
Author: Sunny Ripert <negatif@gmail.com>
Date:   Wed May 7 14:00:59 2008 +0200

    Applied list conventions in AR::Base

commit 5bd18429f09d44e75191bec42a6db04bd33f3030
Author: Sunny Ripert <negatif@gmail.com>
Date:   Wed May 7 13:53:35 2008 +0200

    Renamed Options list to Attributes list whenever they weren't option hashes in AR::Base

commit d912bd5672316454457ae83f6e9dda5197beeb6f
Author: Yaroslav Markin <yaroslav@markin.net>
Date:   Wed May 7 13:50:28 2008 +0400

    Add a filter_parameter_logging usage hint to generated ApplicationController.
    This may help to remind the developer to filter sensitive information from application logs.
    Closes #11578

commit b243de0db3c2605121e055079854af5090d06374
Author: Jack Danger Canty <git@6brand.com>
Date:   Tue May 6 23:39:47 2008 -0700

    doc: disambiguating an example ActiveRecord class

commit f81d771f0657ae8375b84a77a059812cce5d6fd9
Author: Jack Danger Canty <git@6brand.com>
Date:   Tue May 6 23:35:05 2008 -0700

    doc: ActiveRecord::Reflection::AssociationReflection#through_reflection

    Added documentation demonstrating the use of #through_reflection for
    finding intervening reflection objects for HasManyThrough
    and HasOneThrough.

commit ae6b46f00b5b8b2939c6b37ce3329c83de7e71db
Author: Cheah Chu Yeow <chuyeow@gmail.com>
Date:   Wed May 7 13:47:41 2008 +0800

    Document AttributeAssignmentError and MultiparameterAssignmentErrors.

commit 8f463550b597db2156b67733f31aed13487fbc3a
Author: John Barnette <jbarnette@gmail.com>
Date:   Tue May 6 22:46:44 2008 -0700

    Killing/fixing a bunch of outdated language in the AR README.

commit aca44bcd92ef783abdf484b58abdde6786db0f89
Author: Cheah Chu Yeow <chuyeow@gmail.com>
Date:   Wed May 7 13:34:52 2008 +0800

    Make a note about ActiveResource::Timeouterror being raised when ARes calls timeout.

commit 284a930a93fbee16e25d06392779dbf2f03e9e12
Author: Jonathan Dance <jd@wuputah.com>
Date:   Tue May 6 14:58:26 2008 -0400

    improvements to the page caching docs

commit 9482da621390c874da7c921c8bd6230caae7035a
Author: Sunny Ripert <negatif@gmail.com>
Date:   Mon May 5 18:13:40 2008 +0200

    validates_numericality_of() "integer" option really is "only_integer"

commit e9afd6790a8f530528f6597a7f59bb283be754f6
Author: Sunny Ripert <negatif@gmail.com>
Date:   Mon May 5 12:11:59 2008 +0200

    Harmonized hash notation in AR::Base

commit 67ebf14a91ffd970b582be4ff2991d691a9cf3e1
Author: Sunny Ripert <negatif@gmail.com>
Date:   Mon May 5 12:06:19 2008 +0200

    Turned options into rdoc-lists in AR::Base

commit 0ec7c0a41d889d4e5382b9dff72f1aaba89bf297
Author: Marshall Huss <mwhuss@Macbook.local>
Date:   Sun May 4 23:21:33 2008 -0400

    Added information of how to set element_name in the case the user has a name confliction with an existing model

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

10 files changed, 142 insertions, 96 deletions

diff --git a/actionpack/lib/action_controller/assertions/selector_assertions.rb b/actionpack/lib/action_controller/assertions/selector_assertions.rb
index 272b8f6841..9ef093acfc 100644
--- a/actionpack/lib/action_controller/assertions/selector_assertions.rb
+++ b/actionpack/lib/action_controller/assertions/selector_assertions.rb
@@ -21,11 +21,11 @@ module ActionController
     # from the response HTML or elements selected by the enclosing assertion.
     # 
     # In addition to HTML responses, you can make the following assertions:
-    # * #assert_select_rjs    -- Assertions on HTML content of RJS update and
+    # * +assert_select_rjs+ - Assertions on HTML content of RJS update and
     #     insertion operations.
-    # * #assert_select_encoded  -- Assertions on HTML encoded inside XML,
+    # * +assert_select_encoded+ - Assertions on HTML encoded inside XML,
     #     for example for dealing with feed item descriptions.
-    # * #assert_select_email    -- Assertions on the HTML body of an e-mail.
+    # * +assert_select_email+ - Assertions on the HTML body of an e-mail.
     #
     # Also see HTML::Selector to learn how to use selectors.
     module SelectorAssertions
@@ -136,27 +136,27 @@ module ActionController
       # === Equality Tests
       #
       # The equality test may be one of the following:
-      # * <tt>true</tt> -- Assertion is true if at least one element selected.
-      # * <tt>false</tt> -- Assertion is true if no element selected.
-      # * <tt>String/Regexp</tt> -- Assertion is true if the text value of at least
+      # * <tt>true</tt> - Assertion is true if at least one element selected.
+      # * <tt>false</tt> - Assertion is true if no element selected.
+      # * <tt>String/Regexp</tt> - Assertion is true if the text value of at least
       #   one element matches the string or regular expression.
-      # * <tt>Integer</tt> -- Assertion is true if exactly that number of
+      # * <tt>Integer</tt> - Assertion is true if exactly that number of
       #   elements are selected.
-      # * <tt>Range</tt> -- Assertion is true if the number of selected
+      # * <tt>Range</tt> - Assertion is true if the number of selected
       #   elements fit the range.
       # If no equality test specified, the assertion is true if at least one
       # element selected.
       #
       # To perform more than one equality tests, use a hash with the following keys:
-      # * <tt>:text</tt> -- Narrow the selection to elements that have this text
+      # * <tt>:text</tt> - Narrow the selection to elements that have this text
       #   value (string or regexp).
-      # * <tt>:html</tt> -- Narrow the selection to elements that have this HTML
+      # * <tt>:html</tt> - Narrow the selection to elements that have this HTML
       #   content (string or regexp).
-      # * <tt>:count</tt> -- Assertion is true if the number of selected elements
+      # * <tt>:count</tt> - Assertion is true if the number of selected elements
       #   is equal to this value.
-      # * <tt>:minimum</tt> -- Assertion is true if the number of selected
+      # * <tt>:minimum</tt> - Assertion is true if the number of selected
       #   elements is at least this value.
-      # * <tt>:maximum</tt> -- Assertion is true if the number of selected
+      # * <tt>:maximum</tt> - Assertion is true if the number of selected
       #   elements is at most this value.
       #
       # If the method is called with a block, once all equality tests are
diff --git a/actionpack/lib/action_controller/base.rb b/actionpack/lib/action_controller/base.rb
index c6d28b492a..e1bf005f39 100755
--- a/actionpack/lib/action_controller/base.rb
+++ b/actionpack/lib/action_controller/base.rb
@@ -159,28 +159,34 @@ module ActionController #:nodoc:
   #
   #   Hello #{session[:person]}
   #
-  # For removing objects from the session, you can either assign a single key to nil, like <tt>session[:person] = nil</tt>, or you can
-  # remove the entire session with reset_session.
+  # For removing objects from the session, you can either assign a single key to +nil+:
   #
-  # Sessions are stored in a browser cookie that's cryptographically signed, but unencrypted, by default. This prevents
-  # the user from tampering with the session but also allows him to see its contents.
+  #   # removes :person from session
+  #   session[:person] = nil
   #
-  # Do not put secret information in session!
+  # or you can remove the entire session with +reset_session+.
+  #
+  # Sessions are stored by default in a browser cookie that's cryptographically signed, but unencrypted.
+  # This prevents the user from tampering with the session but also allows him to see its contents.
+  #
+  # Do not put secret information in cookie-based sessions!
   #
   # Other options for session storage are:
   #
-  # ActiveRecordStore: sessions are stored in your database, which works better than PStore with multiple app servers and,
-  # unlike CookieStore, hides your session contents from the user. To use ActiveRecordStore, set
+  # * ActiveRecordStore - Sessions are stored in your database, which works better than PStore with multiple app servers and,
+  #   unlike CookieStore, hides your session contents from the user. To use ActiveRecordStore, set
   #
-  #   config.action_controller.session_store = :active_record_store
+  #     config.action_controller.session_store = :active_record_store
   #
-  # in your <tt>environment.rb</tt> and run <tt>rake db:sessions:create</tt>.
+  #   in your <tt>config/environment.rb</tt> and run <tt>rake db:sessions:create</tt>.
   #
-  # MemCacheStore: sessions are stored as entries in your memcached cache.  Set the session store type in <tt>environment.rb</tt>:
+  # * MemCacheStore - Sessions are stored as entries in your memcached cache.
+  #   Set the session store type in <tt>config/environment.rb</tt>:
   #
-  #   config.action_controller.session_store = :mem_cache_store
+  #     config.action_controller.session_store = :mem_cache_store
   #
-  #  This assumes that memcached has been installed and configured properly.  See the MemCacheStore docs for more information.
+  #   This assumes that memcached has been installed and configured properly.
+  #   See the MemCacheStore docs for more information.
   #
   # == Responses
   #
@@ -535,20 +541,20 @@ module ActionController #:nodoc:
       #
       # <tt>url_for</tt> is used to:
       #
-      # All keys given to url_for are forwarded to the Route module, save for the following:
-      # * <tt>:anchor</tt> -- specifies the anchor name to be appended to the path. For example,
+      # All keys given to +url_for+ are forwarded to the Route module, save for the following:
+      # * <tt>:anchor</tt> - Specifies the anchor name to be appended to the path. For example,
       #   <tt>url_for :controller => 'posts', :action => 'show', :id => 10, :anchor => 'comments'</tt>
       #   will produce "/posts/show/10#comments".
-      # * <tt>:only_path</tt> --  if true, returns the relative URL (omitting the protocol, host name, and port) (<tt>false</tt> by default)
-      # * <tt>:trailing_slash</tt> --  if true, adds a trailing slash, as in "/archive/2005/". Note that this
+      # * <tt>:only_path</tt> - If true, returns the relative URL (omitting the protocol, host name, and port) (<tt>false</tt> by default).
+      # * <tt>:trailing_slash</tt> - If true, adds a trailing slash, as in "/archive/2005/". Note that this
       #   is currently not recommended since it breaks caching.
-      # * <tt>:host</tt> -- overrides the default (current) host if provided.
-      # * <tt>:protocol</tt> -- overrides the default (current) protocol if provided.
-      # * <tt>:port</tt> -- optionally specify the port to connect to.
-      # * <tt>:user</tt> -- Inline HTTP authentication (only plucked out if <tt>:password</tt> is also present).
-      # * <tt>:password</tt> -- Inline HTTP authentication (only plucked out if <tt>:user</tt> is also present).
-      # * <tt>:skip_relative_url_root</tt> -- if true, the url is not constructed using the relative_url_root of the request so the path
-      #   will include the web server relative installation directory.
+      # * <tt>:host</tt> - Overrides the default (current) host if provided.
+      # * <tt>:protocol</tt> - Overrides the default (current) protocol if provided.
+      # * <tt>:port</tt> - Optionally specify the port to connect to.
+      # * <tt>:user</tt> - Inline HTTP authentication (only plucked out if <tt>:password</tt> is also present).
+      # * <tt>:password</tt> - Inline HTTP authentication (only plucked out if <tt>:user</tt> is also present).
+      # * <tt>:skip_relative_url_root</tt> - If true, the url is not constructed using the +relative_url_root+
+      #   of the request so the path will include the web server relative installation directory.
       #
       # The URL is generated from the remaining keys in the hash. A URL contains two key parts: the <base> and a query string.
       # Routes composes a query string as the key/value pairs not included in the <base>.
diff --git a/actionpack/lib/action_controller/caching.rb b/actionpack/lib/action_controller/caching.rb
index 08cbd13876..c4063dfb4b 100644
--- a/actionpack/lib/action_controller/caching.rb
+++ b/actionpack/lib/action_controller/caching.rb
@@ -20,7 +20,8 @@ module ActionController #:nodoc:
   #
   # == Caching stores
   #
-  # All the caching stores from ActiveSupport::Cache is available to be used as backends for Action Controller caching.
+  # All the caching stores from ActiveSupport::Cache is available to be used as backends for Action Controller caching. This setting only
+  # affects action and fragment caching as page caching is always written to disk.
   #
   # Configuration examples (MemoryStore is the default):
   #
diff --git a/actionpack/lib/action_controller/caching/pages.rb b/actionpack/lib/action_controller/caching/pages.rb
index 7aa6ce154b..a70ed72f03 100644
--- a/actionpack/lib/action_controller/caching/pages.rb
+++ b/actionpack/lib/action_controller/caching/pages.rb
@@ -4,23 +4,24 @@ require 'uri'
 module ActionController #:nodoc:
   module Caching
     # Page caching is an approach to caching where the entire action output of is stored as a HTML file that the web server
-    # can serve without going through the Action Pack. This can be as much as 100 times faster than going through the process of dynamically
-    # generating the content. Unfortunately, this incredible speed-up is only available to stateless pages where all visitors
-    # are treated the same. Content management systems -- including weblogs and wikis -- have many pages that are a great fit
-    # for this approach, but account-based systems where people log in and manipulate their own data are often less likely candidates.
+    # can serve without going through Action Pack. This is the fastest way to cache your content as opposed to going dynamically
+    # through the process of generating the content. Unfortunately, this incredible speed-up is only available to stateless pages
+    # where all visitors are treated the same. Content management systems -- including weblogs and wikis -- have many pages that are
+    # a great fit for this approach, but account-based systems where people log in and manipulate their own data are often less
+    # likely candidates.
     #
-    # Specifying which actions to cache is done through the <tt>caches</tt> class method:
+    # Specifying which actions to cache is done through the <tt>caches_page</tt> class method:
     #
     #   class WeblogController < ActionController::Base
     #     caches_page :show, :new
     #   end
     #
-    # This will generate cache files such as weblog/show/5 and weblog/new, which match the URLs used to trigger the dynamic
-    # generation. This is how the web server is able pick up a cache file when it exists and otherwise let the request pass on to
-    # the Action Pack to generate it.
+    # This will generate cache files such as <tt>weblog/show/5.html</tt> and <tt>weblog/new.html</tt>,
+    # which match the URLs used to trigger the dynamic generation. This is how the web server is able
+    # pick up a cache file when it exists and otherwise let the request pass on to Action Pack to generate it.
     #
     # Expiration of the cache is handled by deleting the cached file, which results in a lazy regeneration approach where the cache
-    # is not restored before another hit is made against it. The API for doing so mimics the options from url_for and friends:
+    # is not restored before another hit is made against it. The API for doing so mimics the options from +url_for+ and friends:
     #
     #   class WeblogController < ActionController::Base
     #     def update
@@ -35,13 +36,17 @@ module ActionController #:nodoc:
     #
     # == Setting the cache directory
     #
-    # The cache directory should be the document root for the web server and is set using Base.page_cache_directory = "/document/root".
-    # For Rails, this directory has already been set to Rails.public_path (which is usually set to RAILS_ROOT + "/public").
+    # The cache directory should be the document root for the web server and is set using <tt>Base.page_cache_directory = "/document/root"</tt>.
+    # For Rails, this directory has already been set to Rails.public_path (which is usually set to <tt>RAILS_ROOT + "/public"</tt>). Changing
+    # this setting can be useful to avoid naming conflicts with files in <tt>public/</tt>, but doing so will likely require configuring your
+    # web server to look in the new location for cached files.
     #
     # == Setting the cache extension
     #
-    # By default, the cache extension is .html, which makes it easy for the cached files to be picked up by the web server. If you want
-    # something else, like .php or .shtml, just set Base.page_cache_extension.
+    # Most Rails requests do not have an extension, such as <tt>/weblog/new</tt>. In these cases, the page caching mechanism will add one in
+    # order to make it easy for the cached files to be picked up properly by the web server. By default, this cache extension is <tt>.html</tt>.
+    # If you want something else, like <tt>.php</tt> or <tt>.shtml</tt>, just set Base.page_cache_extension. In cases where a request already has an
+    # extension, such as <tt>.xml</tt> or <tt>.rss</tt>, page caching will not add an extension. This allows it to work well with RESTful apps.
     module Pages
       def self.included(base) #:nodoc:
         base.extend(ClassMethods)
diff --git a/actionpack/lib/action_controller/polymorphic_routes.rb b/actionpack/lib/action_controller/polymorphic_routes.rb
index aa0e05dbd7..e2b7716aa2 100644
--- a/actionpack/lib/action_controller/polymorphic_routes.rb
+++ b/actionpack/lib/action_controller/polymorphic_routes.rb
@@ -47,25 +47,27 @@ module ActionController
     # Constructs a call to a named RESTful route for the given record and returns the
     # resulting URL string. For example:
     #
-    #   polymorphic_url(post)
-    #   # calls post_url(post) #=> "http://example.com/posts/1"
+    #   # calls post_url(post)
+    #   polymorphic_url(post) # => "http://example.com/posts/1"
     #
     # ==== Options
-    # * <tt>:action</tt> -- specifies the action prefix for the named route:
-    #   <tt>:new</tt>, <tt>:edit</tt> or <tt>:formatted</tt>. Default is no prefix.
-    # * <tt>:routing_type</tt> -- <tt>:path</tt> or <tt>:url</tt> (default <tt>:url</tt>).
+    #
+    # * <tt>:action</tt> - Specifies the action prefix for the named route:
+    #   <tt>:new</tt>, <tt>:edit</tt>, or <tt>:formatted</tt>. Default is no prefix.
+    # * <tt>:routing_type</tt> - Allowed values are <tt>:path</tt> or <tt>:url</tt>.
+    #   Default is <tt>:url</tt>.
     #
     # ==== Examples
     #
     #   # an Article record
-    #   polymorphic_url(record)  #->  article_url(record)
+    #   polymorphic_url(record)  # same as article_url(record)
     #
     #   # a Comment record
-    #   polymorphic_url(record)  #->  comment_url(record)
+    #   polymorphic_url(record)  # same as comment_url(record)
     #
     #   # it recognizes new records and maps to the collection
     #   record = Comment.new
-    #   polymorphic_url(record)  #->  comments_url()
+    #   polymorphic_url(record)  # same as comments_url()
     #
     def polymorphic_url(record_or_hash_or_array, options = {})
       if record_or_hash_or_array.kind_of?(Array)
diff --git a/actionpack/lib/action_controller/request_forgery_protection.rb b/actionpack/lib/action_controller/request_forgery_protection.rb
index 7e6961d25f..5daf14eb30 100644
--- a/actionpack/lib/action_controller/request_forgery_protection.rb
+++ b/actionpack/lib/action_controller/request_forgery_protection.rb
@@ -69,10 +69,10 @@ module ActionController #:nodoc:
       #
       # Valid Options:
       #
-      # * <tt>:only/:except</tt> - passed to the <tt>before_filter</tt> call.  Set which actions are verified.
+      # * <tt>:only/:except</tt> - Passed to the <tt>before_filter</tt> call.  Set which actions are verified.
       # * <tt>:secret</tt> - Custom salt used to generate the <tt>form_authenticity_token</tt>.
       #   Leave this off if you are using the cookie session store.
-      # * <tt>:digest</tt> - Message digest used for hashing.  Defaults to 'SHA1'
+      # * <tt>:digest</tt> - Message digest used for hashing.  Defaults to 'SHA1'.
       def protect_from_forgery(options = {})
         self.request_forgery_protection_token ||= :authenticity_token
         before_filter :verify_authenticity_token, :only => options.delete(:only), :except => options.delete(:except)
diff --git a/actionpack/lib/action_controller/resources.rb b/actionpack/lib/action_controller/resources.rb
index c5e7dd7359..26f75780c1 100644
--- a/actionpack/lib/action_controller/resources.rb
+++ b/actionpack/lib/action_controller/resources.rb
@@ -236,27 +236,27 @@ module ActionController
     # which takes into account whether <tt>@message</tt> is a new record or not and generates the
     # path and method accordingly.
     #
-    # The #resources method accepts the following options to customize the resulting routes:
-    # * <tt>:collection</tt> - add named routes for other actions that operate on the collection.
+    # The +resources+ method accepts the following options to customize the resulting routes:
+    # * <tt>:collection</tt> - Add named routes for other actions that operate on the collection.
     #   Takes a hash of <tt>#{action} => #{method}</tt>, where method is <tt>:get</tt>/<tt>:post</tt>/<tt>:put</tt>/<tt>:delete</tt>
-    #   or <tt>:any</tt> if the method does not matter.  These routes map to a URL like /messages/rss, with a route of rss_messages_url.
-    # * <tt>:member</tt> - same as <tt>:collection</tt>, but for actions that operate on a specific member.
-    # * <tt>:new</tt> - same as <tt>:collection</tt>, but for actions that operate on the new resource action.
-    # * <tt>:controller</tt> - specify the controller name for the routes.
-    # * <tt>:singular</tt> - specify the singular name used in the member routes.
-    # * <tt>:requirements</tt> - set custom routing parameter requirements.
-    # * <tt>:conditions</tt> - specify custom routing recognition conditions.  Resources sets the <tt>:method</tt> value for the method-specific routes.
-    # * <tt>:as</tt> - specify a different resource name to use in the URL path. For example:
+    #   or <tt>:any</tt> if the method does not matter.  These routes map to a URL like /messages/rss, with a route of +rss_messages_url+.
+    # * <tt>:member</tt> - Same as <tt>:collection</tt>, but for actions that operate on a specific member.
+    # * <tt>:new</tt> - Same as <tt>:collection</tt>, but for actions that operate on the new resource action.
+    # * <tt>:controller</tt> - Specify the controller name for the routes.
+    # * <tt>:singular</tt> - Specify the singular name used in the member routes.
+    # * <tt>:requirements</tt> - Set custom routing parameter requirements.
+    # * <tt>:conditions</tt> - Specify custom routing recognition conditions.  Resources sets the <tt>:method</tt> value for the method-specific routes.
+    # * <tt>:as</tt> - Specify a different resource name to use in the URL path. For example:
     #     # products_path == '/productos'
     #     map.resources :products, :as => 'productos' do |product|
     #       # product_reviews_path(product) == '/productos/1234/comentarios'
     #       product.resources :product_reviews, :as => 'comentarios'
     #     end
     #
-    # * <tt>:has_one</tt> - specify nested resources, this is a shorthand for mapping singleton resources beneath the current.
-    # * <tt>:has_many</tt> -  same has <tt>:has_one</tt>, but for plural resources.
+    # * <tt>:has_one</tt> - Specify nested resources, this is a shorthand for mapping singleton resources beneath the current.
+    # * <tt>:has_many</tt> - Same has <tt>:has_one</tt>, but for plural resources.
     #
-    #   You may directly specify the routing association with has_one and has_many like:
+    #   You may directly specify the routing association with +has_one+ and +has_many+ like:
     #
     #     map.resources :notes, :has_one => :author, :has_many => [:comments, :attachments]
     #
@@ -268,14 +268,14 @@ module ActionController
     #       notes.resources :attachments
     #     end
     #
-    # * <tt>:path_names</tt> - specify different names for the 'new' and 'edit' actions. For example:
+    # * <tt>:path_names</tt> - Specify different names for the 'new' and 'edit' actions. For example:
     #     # new_products_path == '/productos/nuevo'
     #     map.resources :products, :as => 'productos', :path_names => { :new => 'nuevo', :edit => 'editar' }
     #
     #   You can also set default action names from an environment, like this:
     #     config.action_controller.resources_path_names = { :new => 'nuevo', :edit => 'editar' }
     #
-    # * <tt>:path_prefix</tt> - set a prefix to the routes with required route variables.
+    # * <tt>:path_prefix</tt> - Set a prefix to the routes with required route variables.
     #
     #   Weblog comments usually belong to a post, so you might use resources like:
     #
@@ -296,7 +296,7 @@ module ActionController
     #     article_comments_url(:article_id => @article)
     #     article_comment_url(:article_id => @article, :id => @comment)
     #
-    # * <tt>:name_prefix</tt> - define a prefix for all generated routes, usually ending in an underscore.
+    # * <tt>:name_prefix</tt> - Define a prefix for all generated routes, usually ending in an underscore.
     #   Use this if you have named routes that may clash.
     #
     #     map.resources :tags, :path_prefix => '/books/:book_id', :name_prefix => 'book_'
@@ -343,7 +343,7 @@ module ActionController
     #   # --> GET /categories/7/messages/1
     #   #     has named route "category_message"
     #
-    # The #resources method sets HTTP method restrictions on the routes it generates. For example, making an
+    # The +resources+ method sets HTTP method restrictions on the routes it generates. For example, making an
     # HTTP POST on <tt>new_message_url</tt> will raise a RoutingError exception. The default route in
     # <tt>config/routes.rb</tt> overrides this and allows invalid HTTP methods for resource routes.
     def resources(*entities, &block)
diff --git a/actionpack/lib/action_controller/routing.rb b/actionpack/lib/action_controller/routing.rb
index 0bffe21431..6aa266513d 100644
--- a/actionpack/lib/action_controller/routing.rb
+++ b/actionpack/lib/action_controller/routing.rb
@@ -15,7 +15,7 @@ module ActionController
   # The routing module provides URL rewriting in native Ruby. It's a way to
   # redirect incoming requests to controllers and actions. This replaces
   # mod_rewrite rules. Best of all, Rails' Routing works with any web server.
-  # Routes are defined in routes.rb in your RAILS_ROOT/config directory.
+  # Routes are defined in <tt>config/routes.rb</tt>.
   #
   # Consider the following route, installed by Rails when you generate your
   # application:
@@ -53,7 +53,7 @@ module ActionController
   # == Route priority
   #
   # Not all routes are created equally. Routes have priority defined by the
-  # order of appearance of the routes in the routes.rb file. The priority goes
+  # order of appearance of the routes in the <tt>config/routes.rb</tt> file. The priority goes
   # from top to bottom. The last route in that file is at the lowest priority
   # and will be applied last. If no route matches, 404 is returned.
   #
@@ -118,7 +118,7 @@ module ActionController
   #   root_url   # => 'http://www.example.com/'
   #   root_path  # => ''
   #
-  # You can also specify an already-defined named route in your map.root call:
+  # You can also specify an already-defined named route in your <tt>map.root</tt> call:
   #
   #   # In routes.rb
   #   map.new_session :controller => 'sessions', :action => 'new'
@@ -217,7 +217,7 @@ module ActionController
   #   ActionController::Routing::Routes.reload
   #
   # This will clear all named routes and reload routes.rb if the file has been modified from
-  # last load. To absolutely force reloading, use +reload!+.
+  # last load. To absolutely force reloading, use <tt>reload!</tt>.
   #
   # == Testing Routes
   #
@@ -277,6 +277,9 @@ module ActionController
     end
 
     class << self
+	  # Expects an array of controller names as the first argument.  
+	  # Executes the passed block with only the named controllers named available.
+	  # This method is used in internal Rails testing.
       def with_controllers(names)
         prior_controllers = @possible_controllers
         use_controllers! names
@@ -285,6 +288,10 @@ module ActionController
         use_controllers! prior_controllers
       end
 
+	  # Returns an array of paths, cleaned of double-slashes and relative path references.
+	  # * "\\\" and "//"  become "\\" or "/". 
+	  # * "/foo/bar/../config" becomes "/foo/config".
+	  # The returned array is sorted by length, descending.
       def normalize_paths(paths)
         # do the hokey-pokey of path normalization...
         paths = paths.collect do |path|
@@ -303,6 +310,7 @@ module ActionController
         paths = paths.uniq.sort_by { |path| - path.length }
       end
 
+	  # Returns the array of controller names currently available to ActionController::Routing.
       def possible_controllers
         unless @possible_controllers
           @possible_controllers = []
@@ -327,10 +335,28 @@ module ActionController
         @possible_controllers
       end
 
+	  # Replaces the internal list of controllers available to ActionController::Routing with the passed argument.
+	  #   ActionController::Routing.use_controllers!([ "posts", "comments", "admin/comments" ])
       def use_controllers!(controller_names)
         @possible_controllers = controller_names
       end
 
+	  # Returns a controller path for a new +controller+ based on a +previous+ controller path.
+	  # Handles 4 scenarios:
+	  #
+	  # * stay in the previous controller:
+	  #     controller_relative_to( nil, "groups/discussion" ) # => "groups/discussion"
+	  #
+	  # * stay in the previous namespace:
+	  #     controller_relative_to( "posts", "groups/discussion" ) # => "groups/posts"
+	  #
+	  # * forced move to the root namespace:
+	  #     controller_relative_to( "/posts", "groups/discussion" ) # => "posts"
+	  #
+	  # * previous namespace is root:
+	  #     controller_relative_to( "posts", "anything_with_no_slashes" ) # =>"posts"
+	  #
+	  
       def controller_relative_to(controller, previous)
         if controller.nil?           then previous
         elsif controller[0] == ?/    then controller[1..-1]
@@ -344,6 +370,7 @@ module ActionController
     Routes = RouteSet.new
 
     ::Inflector.module_eval do
+	  # Ensures that routes are reloaded when Rails inflections are updated.
       def inflections_with_route_reloading(&block)
         returning(inflections_without_route_reloading(&block)) {
           ActionController::Routing::Routes.reload! if block_given?
diff --git a/actionpack/lib/action_controller/session/active_record_store.rb b/actionpack/lib/action_controller/session/active_record_store.rb
index 379fcd62b6..1e8eb57acb 100644
--- a/actionpack/lib/action_controller/session/active_record_store.rb
+++ b/actionpack/lib/action_controller/session/active_record_store.rb
@@ -13,7 +13,7 @@ class CGI
 
 
     # A session store backed by an Active Record class.  A default class is
-    # provided, but any object duck-typing to an Active Record +Session+ class
+    # provided, but any object duck-typing to an Active Record Session class
     # with text +session_id+ and +data+ attributes is sufficient.
     #
     # The default assumes a +sessions+ tables with columns:
@@ -26,13 +26,13 @@ class CGI
     # ActionController::SessionOverflowError will be raised.
     #
     # You may configure the table name, primary key, and data column.
-    # For example, at the end of config/environment.rb:
+    # For example, at the end of <tt>config/environment.rb</tt>:
     #   CGI::Session::ActiveRecordStore::Session.table_name = 'legacy_session_table'
     #   CGI::Session::ActiveRecordStore::Session.primary_key = 'session_id'
     #   CGI::Session::ActiveRecordStore::Session.data_column_name = 'legacy_session_data'
-    # Note that setting the primary key to the session_id frees you from
-    # having a separate id column if you don't want it.  However, you must
-    # set session.model.id = session.session_id by hand!  A before_filter
+    # Note that setting the primary key to the +session_id+ frees you from
+    # having a separate +id+ column if you don't want it.  However, you must
+    # set <tt>session.model.id = session.session_id</tt> by hand!  A before filter
     # on ApplicationController is a good place.
     #
     # Since the default class is a simple Active Record, you get timestamps
@@ -42,7 +42,7 @@ class CGI
     # You may provide your own session class implementation, whether a
     # feature-packed Active Record or a bare-metal high-performance SQL
     # store, by setting
-    #   +CGI::Session::ActiveRecordStore.session_class = MySessionClass+
+    #   CGI::Session::ActiveRecordStore.session_class = MySessionClass
     # You must implement these methods:
     #   self.find_by_session_id(session_id)
     #   initialize(hash_of_session_id_and_data)
@@ -154,8 +154,13 @@ class CGI
       # The database connection, table name, and session id and data columns
       # are configurable class attributes.  Marshaling and unmarshaling
       # are implemented as class methods that you may override.  By default,
-      # marshaling data is +ActiveSupport::Base64.encode64(Marshal.dump(data))+ and
-      # unmarshaling data is +Marshal.load(ActiveSupport::Base64.decode64(data))+.
+      # marshaling data is
+      #
+      #   ActiveSupport::Base64.encode64(Marshal.dump(data))
+      #
+      # and unmarshaling data is
+      #
+      #   Marshal.load(ActiveSupport::Base64.decode64(data))
       #
       # This marshaling behavior is intended to store the widest range of
       # binary session data in a +text+ column.  For higher performance,
diff --git a/actionpack/lib/action_controller/url_rewriter.rb b/actionpack/lib/action_controller/url_rewriter.rb
index b143806818..3a38f23396 100644
--- a/actionpack/lib/action_controller/url_rewriter.rb
+++ b/actionpack/lib/action_controller/url_rewriter.rb
@@ -29,16 +29,16 @@ module ActionController
     # Generate a url based on the options provided, default_url_options and the
     # routes defined in routes.rb.  The following options are supported:
     #
-    # * <tt>:only_path</tt> If true, the relative url is returned. Defaults to +false+.
-    # * <tt>:protocol</tt> The protocol to connect to. Defaults to 'http'.
-    # * <tt>:host</tt> Specifies the host the link should be targetted at.
+    # * <tt>:only_path</tt> - If true, the relative url is returned. Defaults to +false+.
+    # * <tt>:protocol</tt> - The protocol to connect to. Defaults to 'http'.
+    # * <tt>:host</tt> - Specifies the host the link should be targetted at.
     #   If <tt>:only_path</tt> is false, this option must be
     #   provided either explicitly, or via +default_url_options+.
-    # * <tt>:port</tt> Optionally specify the port to connect to.
-    # * <tt>:anchor</tt> An anchor name to be appended to the path.
-    # * <tt>:skip_relative_url_root</tt> If true, the url is not constructed using the
+    # * <tt>:port</tt> - Optionally specify the port to connect to.
+    # * <tt>:anchor</tt> - An anchor name to be appended to the path.
+    # * <tt>:skip_relative_url_root</tt> - If true, the url is not constructed using the
     #   +relative_url_root+ set in ActionController::AbstractRequest.relative_url_root.
-    # * <tt>:trailing_slash</tt> If true, adds a trailing slash, as in "/archive/2009/"
+    # * <tt>:trailing_slash</tt> - If true, adds a trailing slash, as in "/archive/2009/"
     #
     # Any other key (<tt>:controller</tt>, <tt>:action</tt>, etc.) given to
     # +url_for+ is forwarded to the Routes module.