Merge branch 'master' of github.com:lifo/docrails

* 'master' of github.com:lifo/docrails:
  Adds title to activerecord/lib/active_record/associations/*
  Adds title to the rest of the files in activerecord/lib
  Adds title and proper formatting to docs.
  Adds title where needed.
  Adds basic description and title.
  Adds title and minor changes.

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