Merge remote branch 'origin/master'

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 @@ class NonConcattingString < ActiveSupport::SafeBuffer
   #
   # <%- 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 @@ class NonConcattingString < ActiveSupport::SafeBuffer
   #
   #   <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 @@ class NonConcattingString < ActiveSupport::SafeBuffer
   #
   # 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.

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 CompiledTemplates #:nodoc:
   #   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

actionpack/lib/action_view/helpers/asset_tag_helper.rb

@@ -6,6 +6,7 @@
 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

actionpack/lib/action_view/helpers/atom_feed_helper.rb

 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:

actionpack/lib/action_view/helpers/cache_helper.rb

 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.

actionpack/lib/action_view/helpers/capture_helper.rb

 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

actionpack/lib/action_view/helpers/csrf_helper.rb

 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

actionpack/lib/action_view/helpers/date_helper.rb

@@ -4,6 +4,8 @@
 
 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:
     #

actionpack/lib/action_view/helpers/debug_helper.rb

 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.

actionpack/lib/action_view/helpers/form_helper.rb

@@ -7,6 +7,7 @@
 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.

actionpack/lib/action_view/helpers/form_options_helper.rb

@@ -4,6 +4,7 @@
 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

actionpack/lib/action_view/helpers/form_tag_helper.rb

@@ -4,6 +4,7 @@
 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.

actionpack/lib/action_view/helpers/javascript_helper.rb

 require 'action_view/helpers/tag_helper'
 
 module ActionView
+  # = Action View JavaScript Helpers
   module Helpers
     # Provides functionality for working with JavaScript in your views.
     #

actionpack/lib/action_view/helpers/prototype_helper.rb

@@ -4,6 +4,7 @@
 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,

actionpack/lib/action_view/helpers/raw_output_helper.rb

 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

actionpack/lib/action_view/helpers/record_tag_helper.rb

 module ActionView
+  # = Action View Record Tag Helpers
   module Helpers
     module RecordTagHelper
       # Produces a wrapper DIV element with id and class parameters that

actionpack/lib/action_view/helpers/sanitize_helper.rb

@@ -2,19 +2,25 @@
 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
       #

actionpack/lib/action_view/helpers/scriptaculous_helper.rb

@@ -2,9 +2,11 @@
 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 Helpers
     # 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

actionpack/lib/action_view/helpers/tag_helper.rb

@@ -2,6 +2,7 @@
 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.

actionpack/lib/action_view/helpers/text_helper.rb

@@ -3,6 +3,7 @@
 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

actionpack/lib/action_view/helpers/translation_helper.rb

 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)

actionpack/lib/action_view/helpers/url_helper.rb

@@ -4,6 +4,7 @@
 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).

actionpack/lib/action_view/lookup_context.rb

@@ -2,6 +2,8 @@
 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

actionpack/lib/action_view/paths.rb

 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

actionpack/lib/action_view/railtie.rb

@@ -2,6 +2,7 @@
 require "rails"
 
 module ActionView
+  # = Action View Railtie
   class Railtie < Rails::Railtie
     config.action_view = ActiveSupport::OrderedOptions.new
 

actionpack/lib/action_view/render/layouts.rb

 module ActionView
+  # = Action View Layouts
   module Layouts
     # Returns the contents that are yielded to a layout, given a name or a block.
     #

actionpack/lib/action_view/render/partials.rb

 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

actionpack/lib/action_view/render/rendering.rb

 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:
     #

actionpack/lib/action_view/template.rb

@@ -3,6 +3,7 @@
 require 'active_support/core_ext/kernel/singleton_class'
 
 module ActionView
+  # = Action View Template
   class Template
     extend ActiveSupport::Autoload
 

activerecord/lib/active_record/associations/association_collection.rb

@@ -3,6 +3,8 @@
 
 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.

activerecord/lib/active_record/associations/association_proxy.rb

@@ -2,6 +2,8 @@
 
 module ActiveRecord
   module Associations
+    # = Active Record Associations
+    #
     # This is the root class of all association proxies:
     #
     #   AssociationProxy

activerecord/lib/active_record/associations/belongs_to_association.rb

 module ActiveRecord
+  # = Active Record Belongs To Associations
   module Associations
     class BelongsToAssociation < AssociationProxy #:nodoc:
       def create(attributes = {})

activerecord/lib/active_record/associations/belongs_to_polymorphic_association.rb

 module ActiveRecord
+  # = Active Record Belongs To Polymorphic Association
   module Associations
     class BelongsToPolymorphicAssociation < AssociationProxy #:nodoc:
       def replace(record)

activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb

 module ActiveRecord
+  # = Active Record Has And Belongs To Many Association
   module Associations
     class HasAndBelongsToManyAssociation < AssociationCollection #:nodoc:
       def create(attributes = {})

activerecord/lib/active_record/associations/has_many_association.rb

 module ActiveRecord
+  # = Active Record Has Many Association
   module Associations
     # This is the proxy that handles a has many association.
     #

activerecord/lib/active_record/associations/has_many_through_association.rb

@@ -2,6 +2,7 @@
 require 'active_support/core_ext/object/blank'
 
 module ActiveRecord
+  # = Active Record Has Many Through Association
   module Associations
     class HasManyThroughAssociation < HasManyAssociation #:nodoc:
       include ThroughAssociationScope

activerecord/lib/active_record/associations/has_one_association.rb

 module ActiveRecord
+  # = Active Record Belongs To Has One Association
   module Associations
     class HasOneAssociation < AssociationProxy #:nodoc:
       def initialize(owner, reflection)

activerecord/lib/active_record/associations/has_one_through_association.rb

 require "active_record/associations/through_association_scope"
 
 module ActiveRecord
+  # = Active Record Has One Through Association
   module Associations
     class HasOneThroughAssociation < HasOneAssociation
       include ThroughAssociationScope

activerecord/lib/active_record/associations/through_association_scope.rb

 module ActiveRecord
+  # = Active Record Through Association Scope
   module Associations
     module ThroughAssociationScope
 

activerecord/lib/active_record/migration.rb

@@ -29,7 +29,7 @@ def initialize(name)
     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

activerecord/lib/active_record/named_scope.rb

@@ -4,11 +4,12 @@
 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 ClassMethods
       #   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)

activerecord/lib/active_record/nested_attributes.rb

@@ -15,7 +15,7 @@ class TooManyRecords < ActiveRecordError
       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 @@ class TooManyRecords < ActiveRecordError
     #
     # 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>.
     #

activerecord/lib/active_record/observer.rb

 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

activerecord/lib/active_record/persistence.rb

 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 @@ def destroyed?
       @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 @@ def delete
       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 @@ def destroy
       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 @@ def update_attribute(name, value)
       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!

activerecord/lib/active_record/query_cache.rb

 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.

activerecord/lib/active_record/railtie.rb

@@ -9,6 +9,7 @@
 require "action_controller/railtie"
 
 module ActiveRecord
+  # = Active Record Railtie
   class Railtie < Rails::Railtie
     config.active_record = ActiveSupport::OrderedOptions.new
 

activerecord/lib/active_record/reflection.rb

 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 @@ def reflect_on_aggregation(aggregation)
         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 @@ def reflect_on_all_autosave_associations
     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 @@ def initialize(macro, name, options, active_record)
         @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 @@ def derive_class_name
     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 @@ def derive_primary_key_name
         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

activerecord/lib/active_record/relation.rb

 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 @@ def to_a
       @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 @@ def destroy(id)
     #   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

activerecord/lib/active_record/schema.rb

 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

activerecord/lib/active_record/schema_dumper.rb

@@ -2,6 +2,8 @@
 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 @@ def header(stream)
         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.

activerecord/lib/active_record/serialization.rb

 module ActiveRecord #:nodoc:
+  # = Active Record Serialization
   module Serialization
     extend ActiveSupport::Concern
     include ActiveModel::Serializers::JSON
@@ -22,6 +23,7 @@ def serializable_hash(options = nil)
 
     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

activerecord/lib/active_record/session_store.rb

 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

activerecord/lib/active_record/test_case.rb

 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,

activerecord/lib/active_record/timestamp.rb

 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 Timestamp
     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:
     #

activerecord/lib/active_record/transactions.rb

@@ -11,7 +11,8 @@ class TransactionError < ActiveRecordError # :nodoc:
     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 @@ class TransactionError < ActiveRecordError # :nodoc:
     # 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)

activerecord/lib/active_record/validations.rb

 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

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:
 

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: