Merge remote branch 'origin/master'

58 files changed, 238 insertions, 108 deletions

diff --git a/actionpack/lib/action_view/base.rb b/actionpack/lib/action_view/base.rb
index 4d06ca0d89..a7ba9f374a 100644
--- a/actionpack/lib/action_view/base.rb
+++ b/actionpack/lib/action_view/base.rb
@@ -8,11 +8,13 @@ module ActionView #:nodoc:
   class NonConcattingString < ActiveSupport::SafeBuffer
   end
 
+  # = Action View Base
+  #
   # Action View templates can be written in three ways. If the template file has a <tt>.erb</tt> (or <tt>.rhtml</tt>) extension then it uses a mixture of ERb
   # (included in Ruby) and HTML. If the template file has a <tt>.builder</tt> (or <tt>.rxml</tt>) extension then Jim Weirich's Builder::XmlMarkup library is used.
   # If the template file has a <tt>.rjs</tt> extension then it will use ActionView::Helpers::PrototypeHelper::JavaScriptGenerator.
   #
-  # = ERb
+  # == ERb
   #
   # You trigger ERb by using embeddings such as <% %>, <% -%>, and <%= %>. The <%= %> tag set is used when you want output. Consider the
   # following loop for names:
@@ -32,7 +34,7 @@ module ActionView #:nodoc:
   #
   # <%- and -%> suppress leading and trailing whitespace, including the trailing newline, and can be used interchangeably with <% and %>.
   #
-  # == Using sub templates
+  # === Using sub templates
   #
   # Using sub templates allows you to sidestep tedious replication and extract common display structures in shared templates. The
   # classic example is the use of a header and footer (even though the Action Pack-way would be to use Layouts):
@@ -54,7 +56,7 @@ module ActionView #:nodoc:
   #
   #   <title><%= @page_title %></title>
   #
-  # == Passing local variables to sub templates
+  # === Passing local variables to sub templates
   #
   # You can pass local variables to sub templates by using a hash with the variable names as keys and the objects as values:
   #
@@ -74,7 +76,7 @@ module ActionView #:nodoc:
   #
   # Testing using <tt>defined? headline</tt> will not work. This is an implementation restriction.
   #
-  # == Template caching
+  # === Template caching
   #
   # By default, Rails will compile each template to a method in order to render it. When you alter a template, Rails will
   # check the file's modification time and recompile it.
diff --git a/actionpack/lib/action_view/context.rb b/actionpack/lib/action_view/context.rb
index 88efd4b34f..39d88333e8 100644
--- a/actionpack/lib/action_view/context.rb
+++ b/actionpack/lib/action_view/context.rb
@@ -2,13 +2,12 @@ module ActionView
   module CompiledTemplates #:nodoc:
     # holds compiled template code
   end
-
-  # Action View contexts are supplied to Action Controller
-  # to render template. The default Action View context
-  # is ActionView::Base.
+  # = Action View Context
+  #
+  # Action View contexts are supplied to Action Controller to render template.
+  # The default Action View context is ActionView::Base.
   #
-  # In order to work with ActionController, a Context
-  # must implement:
+  # In order to work with ActionController, a Context must implement:
   #
   # Context#render_partial[options]
   #   - responsible for setting options[:_template]
@@ -21,16 +20,14 @@ module ActionView
   #   options<Hash>:: See _render_template_with_layout in ActionView::Base
   #   partial<Boolean>:: Whether or not the template to render is a partial
   #
-  # An Action View context can also mix in Action View's
-  # helpers. In order to mix in helpers, a context must
-  # implement:
+  # An Action View context can also mix in Action View's helpers. In order to
+  # mix in helpers, a context must implement:
   #
   # Context#controller
   # - Returns an instance of AbstractController
   #
-  # In any case, a context must mix in ActionView::Context,
-  # which stores compiled template and provides the output
-  # buffer.
+  # In any case, a context must mix in ActionView::Context, which stores compiled
+  # template and provides the output buffer.
   module Context
     include CompiledTemplates
     attr_accessor :output_buffer
diff --git a/actionpack/lib/action_view/helpers/asset_tag_helper.rb b/actionpack/lib/action_view/helpers/asset_tag_helper.rb
index 25426a5547..d094b0d8d8 100644
--- a/actionpack/lib/action_view/helpers/asset_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/asset_tag_helper.rb
@@ -6,6 +6,7 @@ require 'active_support/core_ext/file'
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Asset Tag Helpers
   module Helpers #:nodoc:
     # This module provides methods for generating HTML that links views to assets such
     # as images, javascripts, stylesheets, and feeds. These methods do not verify
diff --git a/actionpack/lib/action_view/helpers/atom_feed_helper.rb b/actionpack/lib/action_view/helpers/atom_feed_helper.rb
index 52806f206a..cb5a1404ff 100644
--- a/actionpack/lib/action_view/helpers/atom_feed_helper.rb
+++ b/actionpack/lib/action_view/helpers/atom_feed_helper.rb
@@ -1,10 +1,12 @@
 require 'set'
 
-# Adds easy defaults to writing Atom feeds with the Builder template engine (this does not work on ERb or any other
-# template languages).
 module ActionView
+  # = Action View Atom Feed Helpers
   module Helpers #:nodoc:
     module AtomFeedHelper
+      # Adds easy defaults to writing Atom feeds with the Builder template engine (this does not work on ERb or any other
+      # template languages).
+      #
       # Full usage example:
       #
       #   config/routes.rb:
diff --git a/actionpack/lib/action_view/helpers/cache_helper.rb b/actionpack/lib/action_view/helpers/cache_helper.rb
index 8251ed18f4..f544a9d147 100644
--- a/actionpack/lib/action_view/helpers/cache_helper.rb
+++ b/actionpack/lib/action_view/helpers/cache_helper.rb
@@ -1,8 +1,10 @@
 module ActionView
+  # = Action View Cache Helper
   module Helpers
-    # This helper to exposes a method for caching of view fragments.
-    # See ActionController::Caching::Fragments for usage instructions.
     module CacheHelper
+      # This helper to exposes a method for caching of view fragments.
+      # See ActionController::Caching::Fragments for usage instructions.
+      #
       # A method for caching fragments of a view rather than an entire
       # action or page.  This technique is useful caching pieces like
       # menus, lists of news topics, static HTML fragments, and so on.
diff --git a/actionpack/lib/action_view/helpers/capture_helper.rb b/actionpack/lib/action_view/helpers/capture_helper.rb
index edc6afc622..ea1bf14c96 100644
--- a/actionpack/lib/action_view/helpers/capture_helper.rb
+++ b/actionpack/lib/action_view/helpers/capture_helper.rb
@@ -1,9 +1,11 @@
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Capture Helper
   module Helpers
     # CaptureHelper exposes methods to let you extract generated markup which
     # can be used in other parts of a template or layout file.
+    #
     # It provides a method to capture blocks into variables through capture and
     # a way to capture a block of markup for use in a layout through content_for.
     module CaptureHelper
diff --git a/actionpack/lib/action_view/helpers/csrf_helper.rb b/actionpack/lib/action_view/helpers/csrf_helper.rb
index 41c6b67f91..3d03f6aac6 100644
--- a/actionpack/lib/action_view/helpers/csrf_helper.rb
+++ b/actionpack/lib/action_view/helpers/csrf_helper.rb
@@ -1,7 +1,9 @@
 module ActionView
+  # = Action View CSRF Helper
   module Helpers
     module CsrfHelper
-      # Returns a meta tag with the request forgery protection token for forms to use. Put this in your head.
+      # Returns a meta tag with the cross-site request forgery protection token
+      # for forms to use. Place this in your head.
       def csrf_meta_tag
         if protect_against_forgery?
           %(<meta name="csrf-param" content="#{Rack::Utils.escape_html(request_forgery_protection_token)}"/>\n<meta name="csrf-token" content="#{Rack::Utils.escape_html(form_authenticity_token)}"/>).html_safe
diff --git a/actionpack/lib/action_view/helpers/date_helper.rb b/actionpack/lib/action_view/helpers/date_helper.rb
index 7d846a01dd..6f387bc95a 100644
--- a/actionpack/lib/action_view/helpers/date_helper.rb
+++ b/actionpack/lib/action_view/helpers/date_helper.rb
@@ -4,6 +4,8 @@ require 'active_support/core_ext/hash/slice'
 
 module ActionView
   module Helpers
+    # = Action View Date Helpers
+    #
     # The Date Helper primarily creates select/option tags for different kinds of dates and date elements. All of the
     # select-type methods share a number of common options that are as follows:
     #
diff --git a/actionpack/lib/action_view/helpers/debug_helper.rb b/actionpack/lib/action_view/helpers/debug_helper.rb
index e637dc1474..1491cb073f 100644
--- a/actionpack/lib/action_view/helpers/debug_helper.rb
+++ b/actionpack/lib/action_view/helpers/debug_helper.rb
@@ -1,6 +1,8 @@
 module ActionView
+  # = Action View Debug Helper
+  # 
+  # Provides a set of methods for making it easier to debug Rails objects.
   module Helpers
-    # Provides a set of methods for making it easier to debug Rails objects.
     module DebugHelper
       # Returns a YAML representation of +object+ wrapped with <pre> and </pre>.
       # If the object cannot be converted to YAML using +to_yaml+, +inspect+ will be called instead.
diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb
index 9e2448fe97..a8887a804e 100644
--- a/actionpack/lib/action_view/helpers/form_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_helper.rb
@@ -7,6 +7,7 @@ require 'active_support/core_ext/hash/slice'
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Form Helpers
   module Helpers
     # Form helpers are designed to make working with resources much easier
     # compared to using vanilla HTML.
diff --git a/actionpack/lib/action_view/helpers/form_options_helper.rb b/actionpack/lib/action_view/helpers/form_options_helper.rb
index 6bf78647ec..c564d30302 100644
--- a/actionpack/lib/action_view/helpers/form_options_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_options_helper.rb
@@ -4,6 +4,7 @@ require 'action_view/helpers/form_helper'
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Form Option Helpers
   module Helpers
     # Provides a number of methods for turning different kinds of containers into a set of option tags.
     # == Options
diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb
index 0727375fc0..ea491b2db8 100644
--- a/actionpack/lib/action_view/helpers/form_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb
@@ -4,6 +4,7 @@ require 'active_support/core_ext/object/returning'
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Form Tag Helpers
   module Helpers
     # 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.
diff --git a/actionpack/lib/action_view/helpers/javascript_helper.rb b/actionpack/lib/action_view/helpers/javascript_helper.rb
index b0a7718f22..84f53b842c 100644
--- a/actionpack/lib/action_view/helpers/javascript_helper.rb
+++ b/actionpack/lib/action_view/helpers/javascript_helper.rb
@@ -1,6 +1,7 @@
 require 'action_view/helpers/tag_helper'
 
 module ActionView
+  # = Action View JavaScript Helpers
   module Helpers
     # Provides functionality for working with JavaScript in your views.
     #
diff --git a/actionpack/lib/action_view/helpers/prototype_helper.rb b/actionpack/lib/action_view/helpers/prototype_helper.rb
index a798c3eaef..3038b07143 100644
--- a/actionpack/lib/action_view/helpers/prototype_helper.rb
+++ b/actionpack/lib/action_view/helpers/prototype_helper.rb
@@ -4,6 +4,7 @@ require 'active_support/core_ext/object/returning'
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Prototype Helpers
   module Helpers
     # Prototype[http://www.prototypejs.org/] is a JavaScript library that provides
     # DOM[http://en.wikipedia.org/wiki/Document_Object_Model] manipulation,
diff --git a/actionpack/lib/action_view/helpers/raw_output_helper.rb b/actionpack/lib/action_view/helpers/raw_output_helper.rb
index 8c7f41177d..da7599fa8f 100644
--- a/actionpack/lib/action_view/helpers/raw_output_helper.rb
+++ b/actionpack/lib/action_view/helpers/raw_output_helper.rb
@@ -1,6 +1,15 @@
 module ActionView #:nodoc:
+  # = Action View Raw Output Helper
   module Helpers #:nodoc:
     module RawOutputHelper
+      # This method outputs without escaping a string. Since escaping tags is 
+      # now default, this can be used when you don't want Rails to automatically
+      # escape tags. This is not recommended if the data is coming from the user's
+      # input.
+      #
+      # For example:
+      #
+      # <%=raw @user.name %>
       def raw(stringish)
         stringish.to_s.html_safe
       end
diff --git a/actionpack/lib/action_view/helpers/record_tag_helper.rb b/actionpack/lib/action_view/helpers/record_tag_helper.rb
index a9cf15f418..7433f08777 100644
--- a/actionpack/lib/action_view/helpers/record_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/record_tag_helper.rb
@@ -1,4 +1,5 @@
 module ActionView
+  # = Action View Record Tag Helpers
   module Helpers
     module RecordTagHelper
       # Produces a wrapper DIV element with id and class parameters that
diff --git a/actionpack/lib/action_view/helpers/sanitize_helper.rb b/actionpack/lib/action_view/helpers/sanitize_helper.rb
index f173523f6a..b47818a22a 100644
--- a/actionpack/lib/action_view/helpers/sanitize_helper.rb
+++ b/actionpack/lib/action_view/helpers/sanitize_helper.rb
@@ -2,19 +2,25 @@ require 'action_controller/vendor/html-scanner'
 require 'action_view/helpers/tag_helper'
 
 module ActionView
+  # = Action View Sanitize Helpers
   module Helpers #:nodoc:
     # The SanitizeHelper module provides a set of methods for scrubbing text of undesired HTML elements.
     # These helper methods extend Action View making them callable within your template files.
     module SanitizeHelper
-      # This +sanitize+ helper will html encode all tags and strip all attributes that aren't specifically allowed.
-      # It also strips href/src tags with invalid protocols, like javascript: especially.  It does its best to counter any
-      # tricks that hackers may use, like throwing in unicode/ascii/hex values to get past the javascript: filters.  Check out
+      # This +sanitize+ helper will html encode all tags and strip all attributes that 
+      # aren't specifically allowed.
+      #
+      # It also strips href/src tags with invalid protocols, like javascript: especially.
+      # It does its best to counter any  tricks that hackers may use, like throwing in
+      # unicode/ascii/hex values to get past the javascript: filters.  Check out
       # the extensive test suite.
       #
       #   <%= sanitize @article.body %>
       #
-      # You can add or remove tags/attributes if you want to customize it a bit.  See ActionView::Base for full docs on the
-      # available options.  You can add tags/attributes for single uses of +sanitize+ by passing either the <tt>:attributes</tt> or <tt>:tags</tt> options:
+      # You can add or remove tags/attributes if you want to customize it a bit.
+      # See ActionView::Base for full docs on the available options.  You can add
+      # tags/attributes for single uses of +sanitize+ by passing either the 
+      # <tt>:attributes</tt> or <tt>:tags</tt> options:
       #
       # Normal Use
       #
diff --git a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
index 37319cca1b..7f7776e9c0 100644
--- a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
+++ b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
@@ -2,9 +2,11 @@ require 'action_view/helpers/javascript_helper'
 require 'active_support/json'
 
 module ActionView
+  # = Action View Scriptaculous Helpers
   module Helpers
-    # Provides a set of helpers for calling Scriptaculous JavaScript
-    # functions, including those which create Ajax controls and visual effects.
+    # Provides a set of helpers for calling Scriptaculous[http://script.aculo.us/] 
+    # JavaScript functions, including those which create Ajax controls and visual
+    # effects.
     #
     # To be able to use these helpers, you must include the Prototype
     # JavaScript framework and the Scriptaculous JavaScript library in your
@@ -12,6 +14,7 @@ module ActionView
     # for more information on including the necessary JavaScript.
     #
     # The Scriptaculous helpers' behavior can be tweaked with various options.
+    #
     # See the documentation at http://script.aculo.us for more information on
     # using these helpers in your application.
     module ScriptaculousHelper
diff --git a/actionpack/lib/action_view/helpers/tag_helper.rb b/actionpack/lib/action_view/helpers/tag_helper.rb
index 66277f79fe..d4e8b3d587 100644
--- a/actionpack/lib/action_view/helpers/tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/tag_helper.rb
@@ -2,6 +2,7 @@ require 'active_support/core_ext/object/blank'
 require 'set'
 
 module ActionView
+  # = Action View Tag Helpers
   module Helpers #:nodoc:
     # Provides methods to generate HTML tags programmatically when you can't use
     # a Builder. By default, they output XHTML compliant tags.
diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb
index ccc9156777..9afa989453 100644
--- a/actionpack/lib/action_view/helpers/text_helper.rb
+++ b/actionpack/lib/action_view/helpers/text_helper.rb
@@ -3,6 +3,7 @@ require 'active_support/core_ext/string/filters'
 require 'action_view/helpers/tag_helper'
 
 module ActionView
+  # = Action View Text Helpers
   module Helpers #:nodoc:
     # The TextHelper module provides a set of methods for filtering, formatting
     # and transforming strings, which can reduce the amount of inline Ruby code in
diff --git a/actionpack/lib/action_view/helpers/translation_helper.rb b/actionpack/lib/action_view/helpers/translation_helper.rb
index 0c8829b0b8..dac9c28ab7 100644
--- a/actionpack/lib/action_view/helpers/translation_helper.rb
+++ b/actionpack/lib/action_view/helpers/translation_helper.rb
@@ -1,21 +1,28 @@
 require 'action_view/helpers/tag_helper'
 
 module ActionView
+  # = Action View Translation Helpers
   module Helpers
     module TranslationHelper
-      # Delegates to I18n#translate but also performs three additional functions. First, it'll catch MissingTranslationData exceptions
-      # and turn them into inline spans that contains the missing key, such that you can see in a view what is missing where.
+      # Delegates to I18n#translate but also performs three additional functions.
+      # First, it'll catch MissingTranslationData exceptions and turn them into 
+      # inline spans that contains the missing key, such that you can see in a 
+      # view what is missing where.
       #
-      # Second, it'll scope the key by the current partial if the key starts with a period. So if you call translate(".foo") from the
-      # people/index.html.erb template, you'll actually be calling I18n.translate("people.index.foo"). This makes it less repetitive
-      # to translate many keys within the same partials and gives you a simple framework for scoping them consistently. If you don't
-      # prepend the key with a period, nothing is converted.
+      # Second, it'll scope the key by the current partial if the key starts 
+      # with a period. So if you call <tt>translate(".foo")</tt> from the 
+      # <tt>people/index.html.erb</tt> template, you'll actually be calling 
+      # <tt>I18n.translate("people.index.foo")</tt>. This makes it less repetitive
+      # to translate many keys within the same partials and gives you a simple framework
+      # for scoping them consistently. If you don't prepend the key with a period, 
+      # nothing is converted.
       #
-      # Third, it'll mark the translation as safe HTML if the key has the suffix "_html" or the last element of the key is the word
-      # "html". For example, calling translate("footer_html") or translate("footer.html") will return a safe HTML string that won't
-      # be escaped by other HTML helper methods. This naming convention helps to identify translations that include HTML tags so that
+      # Third, it'll mark the translation as safe HTML if the key has the suffix 
+      # "_html" or the last element of the key is the word "html". For example, 
+      # calling translate("footer_html") or translate("footer.html") will return 
+      # a safe HTML string that won't be escaped by other HTML helper methods. This
+      # naming convention helps to identify translations that include HTML tags so that
       # you know what kind of output to expect when you call translate in a template.
-
       def translate(key, options = {})
         translation = I18n.translate(scope_key_by_partial(key), options.merge!(:raise => true))
         if html_safe_translation_key?(key) && translation.respond_to?(:html_safe)
diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb
index 210f148c02..bcfa6a68d7 100644
--- a/actionpack/lib/action_view/helpers/url_helper.rb
+++ b/actionpack/lib/action_view/helpers/url_helper.rb
@@ -4,6 +4,7 @@ require 'active_support/core_ext/hash/keys'
 require 'action_dispatch'
 
 module ActionView
+  # = Action View URL Helpers
   module Helpers #:nodoc:
     # Provides a set of methods for making links and getting URLs that
     # depend on the routing subsystem (see ActionDispatch::Routing).
diff --git a/actionpack/lib/action_view/lookup_context.rb b/actionpack/lib/action_view/lookup_context.rb
index 823226cb9c..3ea8b86af1 100644
--- a/actionpack/lib/action_view/lookup_context.rb
+++ b/actionpack/lib/action_view/lookup_context.rb
@@ -2,6 +2,8 @@ require 'active_support/core_ext/array/wrap'
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Lookup Context
+  #
   # LookupContext is the object responsible to hold all information required to lookup
   # templates, i.e. view paths and details. The LookupContext is also responsible to
   # generate a key, given to view paths, used in the resolver cache lookup. Since
diff --git a/actionpack/lib/action_view/paths.rb b/actionpack/lib/action_view/paths.rb
index 7f5e5d11b8..9857d688d2 100644
--- a/actionpack/lib/action_view/paths.rb
+++ b/actionpack/lib/action_view/paths.rb
@@ -1,4 +1,5 @@
 module ActionView #:nodoc:
+  # = Action View PathSet
   class PathSet < Array #:nodoc:
     %w(initialize << concat insert push unshift).each do |method|
       class_eval <<-METHOD, __FILE__, __LINE__ + 1
diff --git a/actionpack/lib/action_view/railtie.rb b/actionpack/lib/action_view/railtie.rb
index c606a71e18..e8ea15f47c 100644
--- a/actionpack/lib/action_view/railtie.rb
+++ b/actionpack/lib/action_view/railtie.rb
@@ -2,6 +2,7 @@ require "action_view"
 require "rails"
 
 module ActionView
+  # = Action View Railtie
   class Railtie < Rails::Railtie
     config.action_view = ActiveSupport::OrderedOptions.new
 
diff --git a/actionpack/lib/action_view/render/layouts.rb b/actionpack/lib/action_view/render/layouts.rb
index 1f837b37e2..a474783a20 100644
--- a/actionpack/lib/action_view/render/layouts.rb
+++ b/actionpack/lib/action_view/render/layouts.rb
@@ -1,4 +1,5 @@
 module ActionView
+  # = Action View Layouts
   module Layouts
     # Returns the contents that are yielded to a layout, given a name or a block.
     #
diff --git a/actionpack/lib/action_view/render/partials.rb b/actionpack/lib/action_view/render/partials.rb
index 85f67d4f14..a2c191c580 100644
--- a/actionpack/lib/action_view/render/partials.rb
+++ b/actionpack/lib/action_view/render/partials.rb
@@ -1,6 +1,8 @@
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Partials
+  #
   # There's also a convenience method for rendering sub templates within the current controller that depends on a
   # single object (we call this kind of sub templates for partials). It relies on the fact that partials should
   # follow the naming convention of being prefixed with an underscore -- as to separate them from regular
diff --git a/actionpack/lib/action_view/render/rendering.rb b/actionpack/lib/action_view/render/rendering.rb
index 4d35296932..cb39621d6b 100644
--- a/actionpack/lib/action_view/render/rendering.rb
+++ b/actionpack/lib/action_view/render/rendering.rb
@@ -1,6 +1,7 @@
 require 'active_support/core_ext/object/try'
 
 module ActionView
+  # Action View Rendering
   module Rendering
     # Returns the result of a render that's dictated by the options hash. The primary options are:
     #
diff --git a/actionpack/lib/action_view/template.rb b/actionpack/lib/action_view/template.rb
index 53ad24fdc6..c00557209b 100644
--- a/actionpack/lib/action_view/template.rb
+++ b/actionpack/lib/action_view/template.rb
@@ -3,6 +3,7 @@ require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/kernel/singleton_class'
 
 module ActionView
+  # = Action View Template
   class Template
     extend ActiveSupport::Autoload
 
diff --git a/activerecord/lib/active_record/associations/association_collection.rb b/activerecord/lib/active_record/associations/association_collection.rb
index d9903243ce..5b5094bcab 100644
--- a/activerecord/lib/active_record/associations/association_collection.rb
+++ b/activerecord/lib/active_record/associations/association_collection.rb
@@ -3,6 +3,8 @@ require 'active_support/core_ext/array/wrap'
 
 module ActiveRecord
   module Associations
+    # = Active Record Association Collection
+    #
     # AssociationCollection is an abstract class that provides common stuff to
     # ease the implementation of association proxies that represent
     # collections. See the class hierarchy in AssociationProxy.
diff --git a/activerecord/lib/active_record/associations/association_proxy.rb b/activerecord/lib/active_record/associations/association_proxy.rb
index e88618d278..f333f4d603 100644
--- a/activerecord/lib/active_record/associations/association_proxy.rb
+++ b/activerecord/lib/active_record/associations/association_proxy.rb
@@ -2,6 +2,8 @@ require 'active_support/core_ext/array/wrap'
 
 module ActiveRecord
   module Associations
+    # = Active Record Associations
+    #
     # This is the root class of all association proxies:
     #
     #   AssociationProxy
diff --git a/activerecord/lib/active_record/associations/belongs_to_association.rb b/activerecord/lib/active_record/associations/belongs_to_association.rb
index d2f2267e5c..c2a6495db5 100644
--- a/activerecord/lib/active_record/associations/belongs_to_association.rb
+++ b/activerecord/lib/active_record/associations/belongs_to_association.rb
@@ -1,4 +1,5 @@
 module ActiveRecord
+  # = Active Record Belongs To Associations
   module Associations
     class BelongsToAssociation < AssociationProxy #:nodoc:
       def create(attributes = {})
diff --git a/activerecord/lib/active_record/associations/belongs_to_polymorphic_association.rb b/activerecord/lib/active_record/associations/belongs_to_polymorphic_association.rb
index f6edd6383c..38454ec242 100644
--- a/activerecord/lib/active_record/associations/belongs_to_polymorphic_association.rb
+++ b/activerecord/lib/active_record/associations/belongs_to_polymorphic_association.rb
@@ -1,4 +1,5 @@
 module ActiveRecord
+  # = Active Record Belongs To Polymorphic Association
   module Associations
     class BelongsToPolymorphicAssociation < AssociationProxy #:nodoc:
       def replace(record)
diff --git a/activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb b/activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb
index 7f39a189e4..c989c3536d 100644
--- a/activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb
+++ b/activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb
@@ -1,4 +1,5 @@
 module ActiveRecord
+  # = Active Record Has And Belongs To Many Association
   module Associations
     class HasAndBelongsToManyAssociation < AssociationCollection #:nodoc:
       def create(attributes = {})
diff --git a/activerecord/lib/active_record/associations/has_many_association.rb b/activerecord/lib/active_record/associations/has_many_association.rb
index 0464e8ceea..92c6b3e770 100644
--- a/activerecord/lib/active_record/associations/has_many_association.rb
+++ b/activerecord/lib/active_record/associations/has_many_association.rb
@@ -1,4 +1,5 @@
 module ActiveRecord
+  # = Active Record Has Many Association
   module Associations
     # This is the proxy that handles a has many association.
     #
diff --git a/activerecord/lib/active_record/associations/has_many_through_association.rb b/activerecord/lib/active_record/associations/has_many_through_association.rb
index 5338bb099d..17f850756f 100644
--- a/activerecord/lib/active_record/associations/has_many_through_association.rb
+++ b/activerecord/lib/active_record/associations/has_many_through_association.rb
@@ -2,6 +2,7 @@ require "active_record/associations/through_association_scope"
 require 'active_support/core_ext/object/blank'
 
 module ActiveRecord
+  # = Active Record Has Many Through Association
   module Associations
     class HasManyThroughAssociation < HasManyAssociation #:nodoc:
       include ThroughAssociationScope
diff --git a/activerecord/lib/active_record/associations/has_one_association.rb b/activerecord/lib/active_record/associations/has_one_association.rb
index ea769fd48b..68b8b792ad 100644
--- a/activerecord/lib/active_record/associations/has_one_association.rb
+++ b/activerecord/lib/active_record/associations/has_one_association.rb
@@ -1,4 +1,5 @@
 module ActiveRecord
+  # = Active Record Belongs To Has One Association
   module Associations
     class HasOneAssociation < AssociationProxy #:nodoc:
       def initialize(owner, reflection)
diff --git a/activerecord/lib/active_record/associations/has_one_through_association.rb b/activerecord/lib/active_record/associations/has_one_through_association.rb
index a79bf943d1..fba0a2bfcc 100644
--- a/activerecord/lib/active_record/associations/has_one_through_association.rb
+++ b/activerecord/lib/active_record/associations/has_one_through_association.rb
@@ -1,6 +1,7 @@
 require "active_record/associations/through_association_scope"
 
 module ActiveRecord
+  # = Active Record Has One Through Association
   module Associations
     class HasOneThroughAssociation < HasOneAssociation
       include ThroughAssociationScope
diff --git a/activerecord/lib/active_record/associations/through_association_scope.rb b/activerecord/lib/active_record/associations/through_association_scope.rb
index 93bd6e3185..22e1033a9d 100644
--- a/activerecord/lib/active_record/associations/through_association_scope.rb
+++ b/activerecord/lib/active_record/associations/through_association_scope.rb
@@ -1,4 +1,5 @@
 module ActiveRecord
+  # = Active Record Through Association Scope
   module Associations
     module ThroughAssociationScope
 
diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb
index 4a1d6ac758..b273c33e50 100644
--- a/activerecord/lib/active_record/migration.rb
+++ b/activerecord/lib/active_record/migration.rb
@@ -29,7 +29,7 @@ module ActiveRecord
     end
   end
 
-  # Active Record Migrations
+  # = Active Record Migrations
   # 
   # Migrations can manage the evolution of a schema used by several physical 
   # databases. It's a solution to the common problem of adding a field to make
diff --git a/activerecord/lib/active_record/named_scope.rb b/activerecord/lib/active_record/named_scope.rb
index 3d8f4a030b..47eef9535e 100644
--- a/activerecord/lib/active_record/named_scope.rb
+++ b/activerecord/lib/active_record/named_scope.rb
@@ -4,11 +4,12 @@ require 'active_support/core_ext/kernel/singleton_class'
 require 'active_support/core_ext/object/blank'
 
 module ActiveRecord
+  # = Active Record Named Scopes
   module NamedScope
     extend ActiveSupport::Concern
 
     module ClassMethods
-      # Returns an anonymous scope.
+      # Returns an anonymous \scope.
       #
       #   posts = Post.scoped
       #   posts.size # Fires "select count(*) from  posts" and returns the count
@@ -18,10 +19,12 @@ module ActiveRecord
       #   fruits = fruits.where(:colour => 'red') if options[:red_only]
       #   fruits = fruits.limit(10) if limited?
       #
-      # Anonymous \scopes tend to be useful when procedurally generating complex queries, where passing
-      # intermediate values (scopes) around as first-class objects is convenient.
+      # Anonymous \scopes tend to be useful when procedurally generating complex
+      # queries, where passing intermediate values (scopes) around as first-class 
+      # objects is convenient.
       #
-      # You can define a scope that applies to all finders using ActiveRecord::Base.default_scope.
+      # You can define a scope that applies to all finders using 
+      # ActiveRecord::Base.default_scope.
       def scoped(options = {}, &block)
         if options.present?
           relation = scoped.apply_finder_options(options)
diff --git a/activerecord/lib/active_record/nested_attributes.rb b/activerecord/lib/active_record/nested_attributes.rb
index 767ec85432..99f8b431c8 100644
--- a/activerecord/lib/active_record/nested_attributes.rb
+++ b/activerecord/lib/active_record/nested_attributes.rb
@@ -15,7 +15,7 @@ module ActiveRecord
       self.nested_attributes_options = {}
     end
 
-    # == Nested Attributes
+    # = Active Record Nested Attributes
     #
     # Nested attributes allow you to save attributes on associated records
     # through the parent. By default nested attribute updating is turned off,
@@ -25,6 +25,7 @@ module ActiveRecord
     #
     # The attribute writer is named after the association, which means that
     # in the following example, two new methods are added to your model:
+    # 
     # <tt>author_attributes=(attributes)</tt> and
     # <tt>pages_attributes=(attributes)</tt>.
     #
diff --git a/activerecord/lib/active_record/observer.rb b/activerecord/lib/active_record/observer.rb
index 0ea7fe7365..9554dd8826 100644
--- a/activerecord/lib/active_record/observer.rb
+++ b/activerecord/lib/active_record/observer.rb
@@ -1,6 +1,8 @@
 require 'active_support/core_ext/class/attribute'
 
 module ActiveRecord
+  # = Active Record Observer
+  #
   # Observer classes respond to lifecycle callbacks to implement trigger-like
   # behavior outside the original class. This is a great way to reduce the
   # clutter that normally comes when the model class is burdened with
diff --git a/activerecord/lib/active_record/persistence.rb b/activerecord/lib/active_record/persistence.rb
index 10788630a5..9e28aa2a05 100644
--- a/activerecord/lib/active_record/persistence.rb
+++ b/activerecord/lib/active_record/persistence.rb
@@ -1,6 +1,8 @@
 module ActiveRecord
+  # = Active Record Persistence
   module Persistence
-    # Returns true if this object hasn't been saved yet -- that is, a record for the object doesn't exist yet; otherwise, returns false.
+    # Returns true if this object hasn't been saved yet -- that is, a record 
+    # for the object doesn't exist in the data store yet; otherwise, returns false.
     def new_record?
       @new_record
     end
@@ -10,7 +12,8 @@ module ActiveRecord
       @destroyed
     end
 
-    # Returns if the record is persisted, i.e. it's not a new record and it was not destroyed.
+    # Returns if the record is persisted, i.e. it's not a new record and it was
+    # not destroyed.
     def persisted?
       !(new_record? || destroyed?)
     end
@@ -69,8 +72,8 @@ module ActiveRecord
       freeze
     end
 
-    # Deletes the record in the database and freezes this instance to reflect that no changes should
-    # be made (since they can't be persisted).
+    # Deletes the record in the database and freezes this instance to reflect 
+    # that no changes should be made (since they can't be persisted).
     def destroy
       if persisted?
         self.class.unscoped.where(self.class.arel_table[self.class.primary_key].eq(id)).delete_all
@@ -80,10 +83,13 @@ module ActiveRecord
       freeze
     end
 
-    # Returns an instance of the specified +klass+ with the attributes of the current record. This is mostly useful in relation to
-    # single-table inheritance structures where you want a subclass to appear as the superclass. This can be used along with record
-    # identification in Action Pack to allow, say, <tt>Client < Company</tt> to do something like render <tt>:partial => @client.becomes(Company)</tt>
-    # to render that instance using the companies/company partial instead of clients/client.
+    # Returns an instance of the specified +klass+ with the attributes of the 
+    # current record. This is mostly useful in relation to single-table 
+    # inheritance structures where you want a subclass to appear as the 
+    # superclass. This can be used along with record identification in 
+    # Action Pack to allow, say, <tt>Client < Company</tt> to do something 
+    # like render <tt>:partial => @client.becomes(Company)</tt> to render that
+    # instance using the companies/company partial instead of clients/client.
     #
     # Note: The new instance will share a link to the same attributes as the original class. So any change to the attributes in either
     # instance will affect the other.
@@ -104,14 +110,15 @@ module ActiveRecord
       save(:validate => false)
     end
 
-    # Updates all the attributes from the passed-in Hash and saves the record. If the object is invalid, the saving will
-    # fail and false will be returned.
+    # Updates all the attributes from the passed-in Hash and saves the record. 
+    # If the object is invalid, the saving will fail and false will be returned.
     def update_attributes(attributes)
       self.attributes = attributes
       save
     end
 
-    # Updates an object just like Base.update_attributes but calls save! instead of save so an exception is raised if the record is invalid.
+    # Updates an object just like Base.update_attributes but calls save! instead
+    # of save so an exception is raised if the record is invalid.
     def update_attributes!(attributes)
       self.attributes = attributes
       save!
diff --git a/activerecord/lib/active_record/query_cache.rb b/activerecord/lib/active_record/query_cache.rb
index 093c6c1e55..d9f85a4e5e 100644
--- a/activerecord/lib/active_record/query_cache.rb
+++ b/activerecord/lib/active_record/query_cache.rb
@@ -1,6 +1,7 @@
 require 'active_support/core_ext/object/blank'
 
 module ActiveRecord
+  # = Active Record Query Cache
   class QueryCache
     module ClassMethods
       # Enable the query cache within the block if Active Record is configured.
diff --git a/activerecord/lib/active_record/railtie.rb b/activerecord/lib/active_record/railtie.rb
index a32fb7d399..37f1ec11a6 100644
--- a/activerecord/lib/active_record/railtie.rb
+++ b/activerecord/lib/active_record/railtie.rb
@@ -9,6 +9,7 @@ require "active_model/railtie"
 require "action_controller/railtie"
 
 module ActiveRecord
+  # = Active Record Railtie
   class Railtie < Rails::Railtie
     config.active_record = ActiveSupport::OrderedOptions.new
 
diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb
index d4af3d7d15..a82e5d7ed1 100644
--- a/activerecord/lib/active_record/reflection.rb
+++ b/activerecord/lib/active_record/reflection.rb
@@ -1,12 +1,16 @@
 module ActiveRecord
+  # = Active Record Reflection
   module Reflection # :nodoc:
     extend ActiveSupport::Concern
 
-    # Reflection allows you to interrogate Active Record classes and objects about their associations and aggregations.
-    # This information can, for example, be used in a form builder that took an Active Record object and created input
-    # fields for all of the attributes depending on their type and displayed the associations to other objects.
+    # Reflection allows you to interrogate Active Record classes and objects
+    # about their associations and aggregations. This information can, 
+    # for example, be used in a form builder that took an Active Record object
+    # and created input fields for all of the attributes depending on their type
+    # and displayed the associations to other objects.
     #
-    # You can find the interface for the AggregateReflection and AssociationReflection classes in the abstract MacroReflection class.
+    # You can find the interface for the AggregateReflection and AssociationReflection
+    # classes in the abstract MacroReflection class.
     module ClassMethods
       def create_reflection(macro, name, options, active_record)
         case macro
@@ -43,8 +47,11 @@ module ActiveRecord
         reflections[aggregation].is_a?(AggregateReflection) ? reflections[aggregation] : nil
       end
 
-      # Returns an array of AssociationReflection objects for all the associations in the class. If you only want to reflect on a
-      # certain association type, pass in the symbol (<tt>:has_many</tt>, <tt>:has_one</tt>, <tt>:belongs_to</tt>) for that as the first parameter.
+      # Returns an array of AssociationReflection objects for all the 
+      # associations in the class. If you only want to reflect on a certain 
+      # association type, pass in the symbol (<tt>:has_many</tt>, <tt>:has_one</tt>, 
+      # <tt>:belongs_to</tt>) for that as the first parameter.
+      #
       # Example:
       #
       #   Account.reflect_on_all_associations             # returns an array of all associations
@@ -71,8 +78,9 @@ module ActiveRecord
     end
 
 
-    # Abstract base class for AggregateReflection and AssociationReflection that describes the interface available for both of
-    # those classes. Objects of AggregateReflection and AssociationReflection are returned by the Reflection::ClassMethods.
+    # Abstract base class for AggregateReflection and AssociationReflection that
+    # describes the interface available for both of those classes. Objects of
+    # AggregateReflection and AssociationReflection are returned by the Reflection::ClassMethods.
     class MacroReflection
       attr_reader :active_record
 
@@ -80,13 +88,15 @@ module ActiveRecord
         @macro, @name, @options, @active_record = macro, name, options, active_record
       end
 
-      # Returns the name of the macro.  For example, <tt>composed_of :balance, :class_name => 'Money'</tt> will return
-      # <tt>:balance</tt> or for <tt>has_many :clients</tt> it will return <tt>:clients</tt>.
+      # Returns the name of the macro.  For example, <tt>composed_of :balance, 
+      # :class_name => 'Money'</tt> will return <tt>:balance</tt> or for 
+      # <tt>has_many :clients</tt> it will return <tt>:clients</tt>.
       def name
         @name
       end
 
-      # Returns the macro type. For example, <tt>composed_of :balance, :class_name => 'Money'</tt> will return <tt>:composed_of</tt>
+      # Returns the macro type. For example, 
+      # <tt>composed_of :balance, :class_name => 'Money'</tt> will return <tt>:composed_of</tt>
       # or for <tt>has_many :clients</tt> will return <tt>:has_many</tt>.
       def macro
         @macro
@@ -132,11 +142,13 @@ module ActiveRecord
     end
 
 
-    # Holds all the meta-data about an aggregation as it was specified in the Active Record class.
+    # Holds all the meta-data about an aggregation as it was specified in the 
+    # Active Record class.
     class AggregateReflection < MacroReflection #:nodoc:
     end
 
-    # Holds all the meta-data about an association as it was specified in the Active Record class.
+    # Holds all the meta-data about an association as it was specified in the 
+    # Active Record class.
     class AssociationReflection < MacroReflection #:nodoc:
       # Returns the target association's class:
       #
@@ -306,9 +318,12 @@ module ActiveRecord
         end
     end
 
-    # Holds all the meta-data about a :through association as it was specified in the Active Record class.
+    # Holds all the meta-data about a :through association as it was specified
+    # in the Active Record class.
     class ThroughReflection < AssociationReflection #:nodoc:
-      # Gets the source of the through reflection.  It checks both a singularized and pluralized form for <tt>:belongs_to</tt> or <tt>:has_many</tt>.
+      # Gets the source of the through reflection.  It checks both a singularized
+      # and pluralized form for <tt>:belongs_to</tt> or <tt>:has_many</tt>.
+      #
       # (The <tt>:tags</tt> association on Tagging below.)
       #
       #   class Post < ActiveRecord::Base
diff --git a/activerecord/lib/active_record/relation.rb b/activerecord/lib/active_record/relation.rb
index 5d99a15eda..66970a5ea1 100644
--- a/activerecord/lib/active_record/relation.rb
+++ b/activerecord/lib/active_record/relation.rb
@@ -1,6 +1,7 @@
 require 'active_support/core_ext/object/blank'
 
 module ActiveRecord
+  # = Active Record Relation
   class Relation
     JoinOperation = Struct.new(:relation, :join_class, :on)
     ASSOCIATION_METHODS = [:includes, :eager_load, :preload]
@@ -75,10 +76,12 @@ module ActiveRecord
       @records
     end
 
+    # Returns size of the records.
     def size
       loaded? ? @records.length : count
     end
 
+    # Returns true if there are no records.
     def empty?
       loaded? ? @records.empty? : count.zero?
     end
@@ -240,8 +243,9 @@ module ActiveRecord
     #   Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')")
     #   Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else'])
     #
-    # Both calls delete the affected posts all at once with a single DELETE statement. If you need to destroy dependent
-    # associations or call your <tt>before_*</tt> or +after_destroy+ callbacks, use the +destroy_all+ method instead.
+    # Both calls delete the affected posts all at once with a single DELETE statement. 
+    # If you need to destroy dependent associations or call your <tt>before_*</tt> or 
+    # +after_destroy+ callbacks, use the +destroy_all+ method instead.
     def delete_all(conditions = nil)
       conditions ? where(conditions).delete_all : arel.delete.tap { reset }
     end
diff --git a/activerecord/lib/active_record/schema.rb b/activerecord/lib/active_record/schema.rb
index a833356d15..e2783087ec 100644
--- a/activerecord/lib/active_record/schema.rb
+++ b/activerecord/lib/active_record/schema.rb
@@ -1,6 +1,8 @@
 require 'active_support/core_ext/object/blank'
 
 module ActiveRecord
+  # = Active Record Schema
+  # 
   # Allows programmers to programmatically define a schema in a portable
   # DSL. This means you can define tables, indexes, etc. without using SQL
   # directly, so your applications can more easily support multiple
diff --git a/activerecord/lib/active_record/schema_dumper.rb b/activerecord/lib/active_record/schema_dumper.rb
index 71ef249ee1..a4757773d8 100644
--- a/activerecord/lib/active_record/schema_dumper.rb
+++ b/activerecord/lib/active_record/schema_dumper.rb
@@ -2,6 +2,8 @@ require 'stringio'
 require 'active_support/core_ext/big_decimal'
 
 module ActiveRecord
+  # = Active Record Schema Dumper
+  #
   # This class is used to dump the database schema for some connection to some
   # output format (i.e., ActiveRecord::Schema).
   class SchemaDumper #:nodoc:
@@ -39,13 +41,14 @@ module ActiveRecord
         define_params = @version ? ":version => #{@version}" : ""
 
         stream.puts <<HEADER
-# This file is auto-generated from the current state of the database. Instead of editing this file, 
-# please use the migrations feature of Active Record to incrementally modify your database, and
-# then regenerate this schema definition.
+# This file is auto-generated from the current state of the database. Instead 
+# of editing this file, please use the migrations feature of Active Record to
+# incrementally modify your database, and then regenerate this schema definition.
 #
-# Note that this schema.rb definition is the authoritative source for your database schema. If you need
-# to create the application database on another system, you should be using db:schema:load, not running
-# all the migrations from scratch. The latter is a flawed and unsustainable approach (the more migrations
+# Note that this schema.rb definition is the authoritative source for your 
+# database schema. If you need to create the application database on another
+# system, you should be using db:schema:load, not running all the migrations
+# from scratch. The latter is a flawed and unsustainable approach (the more migrations
 # you'll amass, the slower it'll run and the greater likelihood for issues).
 #
 # It's strongly recommended to check this file into your version control system.
diff --git a/activerecord/lib/active_record/serialization.rb b/activerecord/lib/active_record/serialization.rb
index b49471f7ab..2d8bd184f3 100644
--- a/activerecord/lib/active_record/serialization.rb
+++ b/activerecord/lib/active_record/serialization.rb
@@ -1,4 +1,5 @@
 module ActiveRecord #:nodoc:
+  # = Active Record Serialization
   module Serialization
     extend ActiveSupport::Concern
     include ActiveModel::Serializers::JSON
@@ -22,6 +23,7 @@ module ActiveRecord #:nodoc:
 
     private
       # Add associations specified via the <tt>:includes</tt> option.
+      # 
       # Expects a block that takes as arguments:
       #   +association+ - name of the association
       #   +records+     - the association record(s) to be serialized
diff --git a/activerecord/lib/active_record/session_store.rb b/activerecord/lib/active_record/session_store.rb
index 931872eded..f712a2c94f 100644
--- a/activerecord/lib/active_record/session_store.rb
+++ b/activerecord/lib/active_record/session_store.rb
@@ -1,4 +1,6 @@
 module ActiveRecord
+  # = Active Record Session Store
+  #
   # 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
   # with text +session_id+ and +data+ attributes is sufficient.
@@ -7,6 +9,7 @@ module ActiveRecord
   #   +id+ (numeric primary key),
   #   +session_id+ (text, or longtext if your session data exceeds 65K), and
   #   +data+ (text or longtext; careful if your session data exceeds 65KB).
+  # 
   # The +session_id+ column should always be indexed for speedy lookups.
   # Session data is marshaled to the +data+ column in Base64 format.
   # If the data you write is larger than the column's size limit,
@@ -14,9 +17,11 @@ module ActiveRecord
   #
   # You may configure the table name, primary key, and data column.
   # For example, at the end of <tt>config/environment.rb</tt>:
+  #
   #   ActiveRecord::SessionStore::Session.table_name = 'legacy_session_table'
   #   ActiveRecord::SessionStore::Session.primary_key = 'session_id'
   #   ActiveRecord::SessionStore::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 <tt>session.model.id = session.session_id</tt> by hand!  A before filter
@@ -29,8 +34,11 @@ module ActiveRecord
   # You may provide your own session class implementation, whether a
   # feature-packed Active Record or a bare-metal high-performance SQL
   # store, by setting
+  #
   #   ActiveRecord::SessionStore.session_class = MySessionClass
+  #
   # You must implement these methods:
+  #
   #   self.find_by_session_id(session_id)
   #   initialize(hash_of_session_id_and_data)
   #   attr_reader :session_id
diff --git a/activerecord/lib/active_record/test_case.rb b/activerecord/lib/active_record/test_case.rb
index 0a77ad5fd7..e61a378d17 100644
--- a/activerecord/lib/active_record/test_case.rb
+++ b/activerecord/lib/active_record/test_case.rb
@@ -1,4 +1,7 @@
 module ActiveRecord
+  # = Active Record Test Case
+  # 
+  # Defines some test assertions to test against SQL queries.
   class TestCase < ActiveSupport::TestCase #:nodoc:
     def assert_date_from_db(expected, actual, message = nil)
       # SybaseAdapter doesn't have a separate column type just for dates,
diff --git a/activerecord/lib/active_record/timestamp.rb b/activerecord/lib/active_record/timestamp.rb
index 9fba8f0aca..ffd12d2082 100644
--- a/activerecord/lib/active_record/timestamp.rb
+++ b/activerecord/lib/active_record/timestamp.rb
@@ -1,11 +1,16 @@
 module ActiveRecord
-  # Active Record automatically timestamps create and update operations if the table has fields
-  # named created_at/created_on or updated_at/updated_on.
+  # = Active Record Timestamp
+  # 
+  # Active Record automatically timestamps create and update operations if the
+  # table has fields named <tt>created_at/created_on</tt> or 
+  # <tt>updated_at/updated_on</tt>.
+  #
+  # Timestamping can be turned off by setting:
   #
-  # Timestamping can be turned off by setting
   #   <tt>ActiveRecord::Base.record_timestamps = false</tt>
   #
-  # Timestamps are in the local timezone by default but you can use UTC by setting
+  # Timestamps are in the local timezone by default but you can use UTC by setting:
+  #
   #   <tt>ActiveRecord::Base.default_timezone = :utc</tt>
   module Timestamp
     extend ActiveSupport::Concern
@@ -16,8 +21,9 @@ module ActiveRecord
     end
     
     # Saves the record with the updated_at/on attributes set to the current time.
-    # If the save fails because of validation errors, an ActiveRecord::RecordInvalid exception is raised.
-    # If an attribute name is passed, that attribute is used for the touch instead of the updated_at/on attributes.
+    # If the save fails because of validation errors, an 
+    # ActiveRecord::RecordInvalid exception is raised. If an attribute name is passed,
+    # that attribute is used for the touch instead of the updated_at/on attributes.
     #
     # Examples:
     #
diff --git a/activerecord/lib/active_record/transactions.rb b/activerecord/lib/active_record/transactions.rb
index 620758f5af..b4b146994d 100644
--- a/activerecord/lib/active_record/transactions.rb
+++ b/activerecord/lib/active_record/transactions.rb
@@ -11,7 +11,8 @@ module ActiveRecord
     included do
       define_callbacks :commit, :rollback, :terminator => "result == false", :scope => [:kind, :name]
     end
-
+    # = Active Record Transactions
+    #
     # Transactions are protective blocks where SQL statements are only permanent
     # if they can all succeed as one atomic action. The classic example is a
     # transfer between two accounts where you can only have a deposit if the
@@ -19,7 +20,8 @@ module ActiveRecord
     # the database and guard the data against program errors or database
     # break-downs. So basically you should use transaction blocks whenever you
     # have a number of statements that must be executed together or not at all.
-    # Example:
+    #
+    # For example:
     #
     #   ActiveRecord::Base.transaction do
     #     david.withdrawal(100)
diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb
index be64e00bd1..6b511e83db 100644
--- a/activerecord/lib/active_record/validations.rb
+++ b/activerecord/lib/active_record/validations.rb
@@ -1,6 +1,9 @@
 module ActiveRecord
+  # = Active Record Validations
+  #
   # Raised by <tt>save!</tt> and <tt>create!</tt> when the record is invalid.  Use the
   # +record+ method to retrieve the record which did not validate.
+  #
   #   begin
   #     complex_operation_that_calls_save!_internally
   #   rescue ActiveRecord::RecordInvalid => invalid
diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile
index 73f3ebafbe..f5e70aef41 100644
--- a/railties/guides/source/active_record_querying.textile
+++ b/railties/guides/source/active_record_querying.textile
@@ -51,7 +51,7 @@ Active Record will perform queries on the database for you and is compatible wit
 
 h3. Retrieving Objects from the Database
 
-To retrieve objects from the database, Active Record provides several finder methods. These methods allows you to pass arguments into it to perform certain queries on your database without the need of writing raw SQL.
+To retrieve objects from the database, Active Record provides several finder methods. Each finder method allows you to pass arguments into it to perform certain queries on your database without writing raw SQL.
 
 The methods are:
 * +where+
@@ -66,7 +66,7 @@ The methods are:
 * +readonly+
 * +from+
 
-All of these methods return a Relation
+All of the above methods return an instance of <tt>ActiveRecord::Relation</tt>.
 
 Primary operation of <tt>Model.find(options)</tt> can be summarized as:
 
diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile
index 1c17609b0a..cd7a183def 100644
--- a/railties/guides/source/active_support_core_extensions.textile
+++ b/railties/guides/source/active_support_core_extensions.textile
@@ -159,7 +159,7 @@ NOTE: Defined in +active_support/core_ext/object/duplicable.rb+.
 
 h4. +returning+
 
-The method +returning+ yields its argument to a block and returns it. You tipically use it with a mutable object that gets modified in the block:
+The method +returning+ yields its argument to a block and returns it. You typically use it with a mutable object that gets modified in the block:
 
 <ruby>
 def html_options_for_form(url_for_options, options, *parameters_for_url)
@@ -187,7 +187,7 @@ def log_info(sql, name, ms)
 end
 </ruby>
 
-You can shorten that using +Object#try+. This method is a synonim for +Object#send+ except that it returns +nil+ if sent to +nil+. The previous example could then be rewritten as:
+You can shorten that using +Object#try+. This method is a synonym for +Object#send+ except that it returns +nil+ if sent to +nil+. The previous example could then be rewritten as:
 
 <ruby>
 def log_info(sql, name, ms)
@@ -294,7 +294,7 @@ we get:
 user_path(@user) # => "/users/357-john-smith"
 </ruby>
 
-WARNING. Controllers need to be aware of any redifinition of +to_param+ because when a request like that comes in "357-john-smith" is the value of +params[:id]+.
+WARNING. Controllers need to be aware of any redefinition of +to_param+ because when a request like that comes in "357-john-smith" is the value of +params[:id]+.
 
 NOTE: Defined in +active_support/core_ext/object/to_param.rb+.
 
@@ -332,7 +332,7 @@ Arrays return the result of applying +to_query+ to each element with <tt>_key_[]
 # => "sample%5B%5D=3.4&sample%5B%5D=-45.6"
 </ruby>
 
-Hashes also respond to +to_query+ but with a different signature. If no argument is passed a call generates a sorted series of key/value assigments calling +to_query(key)+ on its values. Then it joins the result with "&":
+Hashes also respond to +to_query+ but with a different signature. If no argument is passed a call generates a sorted series of key/value assignments calling +to_query(key)+ on its values. Then it joins the result with "&":
 
 <ruby>
 {:c => 3, :b => 2, :a => 1}.to_query # => "a=1&b=2&c=3"
@@ -656,9 +656,9 @@ h5. Internal Attributes
 
 When you are defining an attribute in a class that is meant to be subclassed name collisions are a risk. That's remarkably important for libraries.
 
-Active Support defines the macros +attr_internal_reader+, +attr_internal_writer+, and +attr_internal_accessor+. They behave like their Ruby builtin +attr_*+ counterparts, except they name the unerlying instace variable in a way that makes collisions less likely.
+Active Support defines the macros +attr_internal_reader+, +attr_internal_writer+, and +attr_internal_accessor+. They behave like their Ruby builtin +attr_*+ counterparts, except they name the underlying instance variable in a way that makes collisions less likely.
 
-The macro +attr_internal+ is a synonim for +attr_internal_accessor+:
+The macro +attr_internal+ is a synonym for +attr_internal_accessor+:
 
 <ruby>
 # library
@@ -721,7 +721,7 @@ h4. Method Delegation
 
 The class method +delegate+ offers an easy way to forward methods.
 
-For example, if +User+ has some details like the age factored out to +Profile+, it could be handy to still be able to acces such attribute directly, <tt>user.age</tt>, instead of having to explicit the chain <tt>user.profile.age</tt>.
+For example, if +User+ has some details like the age factored out to +Profile+, it could be handy to still be able to access such attributes directly, <tt>user.age</tt>, instead of having to explicit the chain <tt>user.profile.age</tt>.
 
 That can be accomplished by hand:
 
@@ -935,7 +935,7 @@ NOTE: Defined in +active_support/core_ext/module/synchronization.rb+.
 
 h4. Reachable
 
-A named module is reachable if it is stored in its correspoding constant. It means you can reach the module object via the constant.
+A named module is reachable if it is stored in its corresponding constant. It means you can reach the module object via the constant.
 
 That is what ordinarily happens, if a module is called "M", the +M+ constant exists and holds it:
 
@@ -1016,7 +1016,7 @@ h3. Extensions to +Class+
 
 h4. Class Attributes
 
-The method +Class#class_attribute+ declares one or more inheritable class attributes that can be overriden at any level down the hierarchy:
+The method +Class#class_attribute+ declares one or more inheritable class attributes that can be overridden at any level down the hierarchy:
 
 <ruby>
 class A
@@ -1088,7 +1088,7 @@ NOTE: Defined in +active_support/core_ext/class/attribute_accessors.rb+.
 
 h4. Class Inheritable Attributes
 
-Class variables are shared down the inheritance tree. Class instance variables are not shared, but they are not inherited either. The macros +class_inheritable_reader+, +class_inheritable_writer+, and +class_inheritable_accessor+ provide accesors for class-level data which is inherited but not shared with children:
+Class variables are shared down the inheritance tree. Class instance variables are not shared, but they are not inherited either. The macros +class_inheritable_reader+, +class_inheritable_writer+, and +class_inheritable_accessor+ provide accessors for class-level data which is inherited but not shared with children:
 
 <ruby>
 module ActionController
@@ -1204,7 +1204,7 @@ s.html_safe? # => true
 s            # => "<script>...</script>"
 </ruby>
 
-It is your responsability to ensure calling +html_safe+ on a particular string is fine.
+It is your responsibility to ensure calling +html_safe+ on a particular string is fine.
 
 NOTE: For performance reasons safe strings are implemented in a way that cannot offer an in-place +html_safe!+ variant.
 
@@ -1377,7 +1377,7 @@ The method +pluralize+ returns the plural of its receiver:
 "equipment".pluralize # => "equipment"
 </ruby>
 
-As the previous example shows, Active Support knows some irregular plurals and uncountable nouns. Builtin rules can be extended in +config/initializers/inflections.rb+. That file is generated by the +rails+ command and has instructions in comments.
+As the previous example shows, Active Support knows some irregular plurals and uncountable nouns. Built-in rules can be extended in +config/initializers/inflections.rb+. That file is generated by the +rails+ command and has instructions in comments.
 
 Active Record uses this method to compute the default table name that corresponds to a model:
 
@@ -1760,7 +1760,7 @@ h3. Extensions to +Float+
 
 h4. +round+
 
-The builtin method +Float#round+ rounds a float to the nearest integer. Active Support adds an optional parameter to let you specify a precision:
+The built-in method +Float#round+ rounds a float to the nearest integer. Active Support adds an optional parameter to let you specify a precision:
 
 <ruby>
 Math::E.round(4) # => 2.7183
@@ -1925,7 +1925,7 @@ Similarly, +from+ returns the tail from the element at the passed index on:
 [].from(0)           # => []
 </ruby>
 
-The methods +second+, +third+, +fourth+, and +fifth+ return the corresponding element (+first+ is builtin). Thanks to social wisdom and positive constructiveness all around, +forty_two+ is also available.
+The methods +second+, +third+, +fourth+, and +fifth+ return the corresponding element (+first+ is built-in). Thanks to social wisdom and positive constructiveness all around, +forty_two+ is also available.
 
 NOTE: Defined in +active_support/core_ext/array/access.rb+.
 
@@ -2120,7 +2120,7 @@ NOTE: Defined in +active_support/core_ext/array/conversions.rb+.
 
 h4. Wrapping
 
-The class method +Array.wrap+ behaves like the function +Array()+ except that it does not try to call +to_a+ on its argument. That changes the behaviour for enumerables:
+The class method +Array.wrap+ behaves like the function +Array()+ except that it does not try to call +to_a+ on its argument. That changes the behavior for enumerables:
 
 <ruby>
 Array.wrap(:foo => :bar) # => [{:foo => :bar}]
@@ -2282,7 +2282,7 @@ NOTE: Defined in +active_support/core_ext/hash/conversions.rb+.
 
 h4. Merging
 
-Ruby has a builtin method +Hash#merge+ that merges two hashes:
+Ruby has a built-in method +Hash#merge+ that merges two hashes:
 
 <ruby>
 {:a => 1, :b => 1}.merge(:a => 0, :c => 2)
@@ -2511,7 +2511,7 @@ NOTE: Defined in +active_support/core_ext/hash/keys.rb+.
 
 h4. Slicing
 
-Ruby has builtin support for taking slices out of strings and arrays. Active Support extends slicing to hashes:
+Ruby has built-in support for taking slices out of strings and arrays. Active Support extends slicing to hashes:
 
 <ruby>
 {:a => 1, :b => 2, :c => 3}.slice(:a, :c)
@@ -2625,7 +2625,7 @@ Active Support extends this method so that the argument may be another range in
 (1...9).include?(3..9)  # => false
 </ruby>
 
-WARNING: The orginal +Range#include?+ is still the one aliased to +Range#===+.
+WARNING: The original +Range#include?+ is still the one aliased to +Range#===+.
 
 NOTE: Defined in +active_support/core_ext/range/include_range.rb+.
 
@@ -3080,7 +3080,7 @@ Active Support adds +missing_name?+ to +NameError+, which tests whether the exce
 
 The name may be given as a symbol or string. A symbol is tested against the bare constant name, a string is against the fully-qualified constant name.
 
-TIP: A symbol can represent a fully-qualified constant name as in +:"ActiveRecord::Base"+, so the behaviour for symbols is defined for convenience, not because it has to be that way technically.
+TIP: A symbol can represent a fully-qualified constant name as in +:"ActiveRecord::Base"+, so the behavior for symbols is defined for convenience, not because it has to be that way technically.
 
 For example, when an action of +PostsController+ is called Rails tries optimistically to use +PostsHelper+. It is OK that the helper module does not exist, so if an exception for that constant name is raised it should be silenced. But it could be the case that +posts_helper.rb+ raises a +NameError+ due to an actual unknown constant. That should be reraised. The method +missing_name?+ provides a way to distinguish both cases: