activerecord 3.1.12 → 3.2.0.rc1

data/README.rdoc

@@ -197,7 +197,7 @@ Admit the Database:
 
 == Download and installation
 
-The latest version of Active Record can be installed with Rubygems:
+The latest version of Active Record can be installed with RubyGems:
 
   % [sudo] gem install activerecord
 
@@ -215,7 +215,7 @@ Active Record is released under the MIT license.
 
 API documentation is at
 
-* http://api.rubyonrails.com
+* http://api.rubyonrails.org
 
 Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
 

data/examples/performance.rb

@@ -1,9 +1,7 @@
+TIMES = (ENV['N'] || 10000).to_i
+
 require File.expand_path('../../../load_paths', __FILE__)
 require "active_record"
-require 'benchmark/ips'
-
-TIME    = (ENV['BENCHMARK_TIME'] || 20).to_i
-RECORDS = (ENV['BENCHMARK_RECORDS'] || TIME*1000).to_i
 
 conn = { :adapter => 'sqlite3', :database => ':memory:' }
 
@@ -31,6 +29,14 @@ class Exhibit < ActiveRecord::Base
   def look; attributes end
   def feel; look; user.name end
 
+  def self.with_name
+    where("name IS NOT NULL")
+  end
+
+  def self.with_notes
+    where("notes IS NOT NULL")
+  end
+
   def self.look(exhibits) exhibits.each { |e| e.look } end
   def self.feel(exhibits) exhibits.each { |e| e.feel } end
 end
@@ -39,7 +45,14 @@ puts 'Generating data...'
 
 module ActiveRecord
   class Faker
-    LOREM = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse non aliquet diam. Curabitur vel urna metus, quis malesuada elit. Integer consequat tincidunt felis. Etiam non erat dolor. Vivamus imperdiet nibh sit amet diam eleifend id posuere diam malesuada. Mauris at accumsan sem. Donec id lorem neque. Fusce erat lorem, ornare eu congue vitae, malesuada quis neque. Maecenas vel urna a velit pretium fermentum. Donec tortor enim, tempor venenatis egestas a, tempor sed ipsum. Ut arcu justo, faucibus non imperdiet ac, interdum at diam. Pellentesque ipsum enim, venenatis ut iaculis vitae, varius vitae sem. Sed rutrum quam ac elit euismod bibendum. Donec ultricies ultricies magna, at lacinia libero mollis aliquam. Sed ac arcu in tortor elementum tincidunt vel interdum sem. Curabitur eget erat arcu. Praesent eget eros leo. Nam magna enim, sollicitudin vehicula scelerisque in, vulputate ut libero. Praesent varius tincidunt commodo".split
+    LOREM = %Q{Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse non aliquet diam. Curabitur vel urna metus, quis malesuada elit.
+     Integer consequat tincidunt felis. Etiam non erat dolor. Vivamus imperdiet nibh sit amet diam eleifend id posuere diam malesuada. Mauris at accumsan sem.
+     Donec id lorem neque. Fusce erat lorem, ornare eu congue vitae, malesuada quis neque. Maecenas vel urna a velit pretium fermentum. Donec tortor enim,
+     tempor venenatis egestas a, tempor sed ipsum. Ut arcu justo, faucibus non imperdiet ac, interdum at diam. Pellentesque ipsum enim, venenatis ut iaculis vitae,
+     varius vitae sem. Sed rutrum quam ac elit euismod bibendum. Donec ultricies ultricies magna, at lacinia libero mollis aliquam. Sed ac arcu in tortor elementum
+     tincidunt vel interdum sem. Curabitur eget erat arcu. Praesent eget eros leo. Nam magna enim, sollicitudin vehicula scelerisque in, vulputate ut libero.
+     Praesent varius tincidunt commodo}.split
+
     def self.name
       LOREM.grep(/^\w*$/).sort_by { rand }.first(2).join ' '
     end
@@ -59,8 +72,8 @@ end
 notes = ActiveRecord::Faker::LOREM.join ' '
 today = Date.today
 
-puts "Inserting #{RECORDS} users and exhibits..."
-RECORDS.times do
+puts 'Inserting 10,000 users and exhibits...'
+10_000.times do
   user = User.create(
     :created_at => today,
     :name       => ActiveRecord::Faker.name,
@@ -75,7 +88,9 @@ RECORDS.times do
   )
 end
 
-Benchmark.ips(TIME) do |x|
+require 'benchmark'
+
+Benchmark.bm(46) do |x|
   ar_obj       = Exhibit.find(1)
   attrs        = { :name => 'sam' }
   attrs_first  = { :name => 'sam' }
@@ -86,68 +101,77 @@ Benchmark.ips(TIME) do |x|
     :created_at => Date.today
   }
 
-  x.report("Model#id") do
-    ar_obj.id
+  x.report("Model#id (x#{(TIMES * 100).ceil})") do
+    (TIMES * 100).ceil.times { ar_obj.id }
   end
 
   x.report 'Model.new (instantiation)' do
-    Exhibit.new
+    TIMES.times { Exhibit.new }
   end
 
   x.report 'Model.new (setting attributes)' do
-    Exhibit.new(attrs)
+    TIMES.times { Exhibit.new(attrs) }
   end
 
   x.report 'Model.first' do
-    Exhibit.first.look
+    TIMES.times { Exhibit.first.look }
+  end
+
+  x.report 'Model.named_scope' do
+    TIMES.times { Exhibit.limit(10).with_name.with_notes }
   end
 
-  x.report("Model.all limit(100)") do
-    Exhibit.look Exhibit.limit(100)
+  x.report("Model.all limit(100) (x#{(TIMES / 10).ceil})") do
+    (TIMES / 10).ceil.times { Exhibit.look Exhibit.limit(100) }
   end
 
-  x.report "Model.all limit(100) with relationship" do
-    Exhibit.feel Exhibit.limit(100).includes(:user)
+  x.report "Model.all limit(100) with relationship (x#{(TIMES / 10).ceil})" do
+    (TIMES / 10).ceil.times { Exhibit.feel Exhibit.limit(100).includes(:user) }
   end
 
-  x.report "Model.all limit(10,000)" do
-    Exhibit.look Exhibit.limit(10000)
+  x.report "Model.all limit(10,000) x(#{(TIMES / 1000).ceil})" do
+    (TIMES / 1000).ceil.times { Exhibit.look Exhibit.limit(10000) }
   end
 
   x.report 'Model.create' do
-    Exhibit.create(exhibit)
+    TIMES.times { Exhibit.create(exhibit) }
   end
 
   x.report 'Resource#attributes=' do
-    e = Exhibit.new(attrs_first)
-    e.attributes = attrs_second
+    TIMES.times {
+      exhibit = Exhibit.new(attrs_first)
+      exhibit.attributes = attrs_second
+    }
   end
 
   x.report 'Resource#update' do
-    Exhibit.first.update_attributes(:name => 'bob')
+    TIMES.times { Exhibit.first.update_attributes(:name => 'bob') }
   end
 
   x.report 'Resource#destroy' do
-    Exhibit.first.destroy
+    TIMES.times { Exhibit.first.destroy }
   end
 
   x.report 'Model.transaction' do
-    Exhibit.transaction { Exhibit.new }
+    TIMES.times { Exhibit.transaction { Exhibit.new } }
   end
 
   x.report 'Model.find(id)' do
-    User.find(1)
+    id = Exhibit.first.id
+    TIMES.times { Exhibit.find(id) }
   end
 
   x.report 'Model.find_by_sql' do
-    Exhibit.find_by_sql("SELECT * FROM exhibits WHERE id = #{(rand * 1000 + 1).to_i}").first
+    TIMES.times {
+      Exhibit.find_by_sql("SELECT * FROM exhibits WHERE id = #{(rand * 1000 + 1).to_i}").first
+    }
   end
 
-  x.report "Model.log" do
-    Exhibit.connection.send(:log, "hello", "world") {}
+  x.report "Model.log x(#{TIMES * 10})" do
+    (TIMES * 10).times { Exhibit.connection.send(:log, "hello", "world") {} }
   end
 
-  x.report "AR.execute(query)" do
-    ActiveRecord::Base.connection.execute("Select * from exhibits where id = #{(rand * 1000 + 1).to_i}")
+  x.report "AR.execute(query) (#{TIMES / 2})" do
+    (TIMES / 2).times { ActiveRecord::Base.connection.execute("Select * from exhibits where id = #{(rand * 1000 + 1).to_i}") }
   end
 end

data/lib/active_record.rb

@@ -34,10 +34,12 @@ module ActiveRecord
   eager_autoload do
     autoload :ActiveRecordError, 'active_record/errors'
     autoload :ConnectionNotEstablished, 'active_record/errors'
+    autoload :ConnectionAdapters, 'active_record/connection_adapters/abstract_adapter'
 
     autoload :Aggregations
     autoload :Associations
     autoload :AttributeMethods
+    autoload :AttributeAssignment
     autoload :AutosaveAssociation
 
     autoload :Relation
@@ -49,29 +51,42 @@ module ActiveRecord
       autoload :PredicateBuilder
       autoload :SpawnMethods
       autoload :Batches
+      autoload :Explain
+      autoload :Delegation
     end
 
     autoload :Base
     autoload :Callbacks
     autoload :CounterCache
+    autoload :DynamicMatchers
     autoload :DynamicFinderMatch
     autoload :DynamicScopeMatch
+    autoload :Explain
+    autoload :IdentityMap
+    autoload :Inheritance
+    autoload :Integration
     autoload :Migration
     autoload :Migrator, 'active_record/migration'
-    autoload :NamedScope
+    autoload :ModelSchema
     autoload :NestedAttributes
     autoload :Observer
     autoload :Persistence
     autoload :QueryCache
+    autoload :Querying
+    autoload :ReadonlyAttributes
     autoload :Reflection
+    autoload :Result
+    autoload :Sanitization
     autoload :Schema
     autoload :SchemaDumper
+    autoload :Scoping
     autoload :Serialization
     autoload :SessionStore
+    autoload :Store
     autoload :Timestamp
     autoload :Transactions
+    autoload :Translation
     autoload :Validations
-    autoload :IdentityMap
   end
 
   module Coders
@@ -89,6 +104,8 @@ module ActiveRecord
       autoload :Read
       autoload :TimeZoneConversion
       autoload :Write
+      autoload :Serialization
+      autoload :DeprecatedUnderscoreRead
     end
   end
 
@@ -110,6 +127,15 @@ module ActiveRecord
     end
   end
 
+  module Scoping
+    extend ActiveSupport::Autoload
+
+    eager_autoload do
+      autoload :Named
+      autoload :Default
+    end
+  end
+
   autoload :TestCase
   autoload :TestFixtures, 'active_record/fixtures'
 end

data/lib/active_record/aggregations.rb

@@ -46,7 +46,7 @@ module ActiveRecord
     #
     #    def <=>(other_money)
     #      if currency == other_money.currency
-    #        amount <=> other_money.amount
+    #        amount <=> amount
     #      else
     #        amount <=> other_money.exchange_to(currency).amount
     #      end
@@ -176,7 +176,7 @@ module ActiveRecord
       #   order in which mappings are defined determines the order in which attributes are sent to the
       #   value class constructor.
       # * <tt>:allow_nil</tt> - Specifies that the value object will not be instantiated when all mapped
-      #   attributes are +nil+.  Setting the value object to +nil+ has the effect of writing +nil+ to all
+      #   attributes are +nil+. Setting the value object to +nil+ has the effect of writing +nil+ to all
       #   mapped attributes.
       #   This defaults to +false+.
       # * <tt>:constructor</tt> - A symbol specifying the name of the constructor method or a Proc that

data/lib/active_record/associations.rb

@@ -5,7 +5,6 @@ require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/string/conversions'
 require 'active_support/core_ext/module/remove_method'
 require 'active_support/core_ext/class/attribute'
-require 'active_support/deprecation'
 
 module ActiveRecord
   class InverseOfAssociationNotFoundError < ActiveRecordError #:nodoc:
@@ -71,7 +70,7 @@ module ActiveRecord
     end
   end
 
-  class HasManyThroughNestedAssociationsAreReadonly < ActiveRecordError #:nodoc
+  class HasManyThroughNestedAssociationsAreReadonly < ActiveRecordError #:nodoc:
     def initialize(owner, reflection)
       super("Cannot modify association '#{owner.class.name}##{reflection.name}' because it goes through more than one other association.")
     end
@@ -114,7 +113,6 @@ module ActiveRecord
     autoload :SingularAssociation,   'active_record/associations/singular_association'
     autoload :CollectionAssociation, 'active_record/associations/collection_association'
     autoload :CollectionProxy,       'active_record/associations/collection_proxy'
-    autoload :AssociationCollection, 'active_record/associations/collection_proxy'
 
     autoload :BelongsToAssociation,            'active_record/associations/belongs_to_association'
     autoload :BelongsToPolymorphicAssociation, 'active_record/associations/belongs_to_polymorphic_association'
@@ -193,11 +191,31 @@ module ActiveRecord
     # * <tt>Project#portfolio, Project#portfolio=(portfolio), Project#portfolio.nil?</tt>
     # * <tt>Project#project_manager, Project#project_manager=(project_manager), Project#project_manager.nil?,</tt>
     # * <tt>Project#milestones.empty?, Project#milestones.size, Project#milestones, Project#milestones<<(milestone),</tt>
-    #   <tt>Project#milestones.delete(milestone), Project#milestones.find(milestone_id), Project#milestones.find(:all, options),</tt>
+    #   <tt>Project#milestones.delete(milestone), Project#milestones.find(milestone_id), Project#milestones.all(options),</tt>
     #   <tt>Project#milestones.build, Project#milestones.create</tt>
     # * <tt>Project#categories.empty?, Project#categories.size, Project#categories, Project#categories<<(category1),</tt>
     #   <tt>Project#categories.delete(category1)</tt>
     #
+    # === Overriding generated methods
+    #
+    # Association methods are generated in a module that is included into the model class,
+    # which allows you to easily override with your own methods and call the original
+    # generated method with +super+. For example:
+    #
+    #   class Car < ActiveRecord::Base
+    #     belongs_to :owner
+    #     belongs_to :old_owner
+    #     def owner=(new_owner)
+    #       self.old_owner = self.owner
+    #       super
+    #     end
+    #   end
+    #
+    # If your model class is <tt>Project</tt>, the module is
+    # named <tt>Project::GeneratedFeatureMethods</tt>. The GeneratedFeatureMethods module is
+    # included in the model class immediately after the (anonymous) generated attributes methods
+    # module, meaning an association will override the methods for an attribute with the same name.
+    #
     # === A word of warning
     #
     # Don't create associations that have the same name as instance methods of
@@ -471,9 +489,9 @@ module ActiveRecord
     # === Association Join Models
     #
     # Has Many associations can be configured with the <tt>:through</tt> option to use an
-    # explicit join model to retrieve the data.  This operates similarly to a
-    # +has_and_belongs_to_many+ association.  The advantage is that you're able to add validations,
-    # callbacks, and extra attributes on the join model.  Consider the following schema:
+    # explicit join model to retrieve the data. This operates similarly to a
+    # +has_and_belongs_to_many+ association. The advantage is that you're able to add validations,
+    # callbacks, and extra attributes on the join model. Consider the following schema:
     #
     #   class Author < ActiveRecord::Base
     #     has_many :authorships
@@ -530,7 +548,7 @@ module ActiveRecord
     #   @group.avatars                                # selects all avatars by going through the User join model.
     #
     # An important caveat with going through +has_one+ or +has_many+ associations on the
-    # join model is that these associations are *read-only*.  For example, the following
+    # join model is that these associations are *read-only*. For example, the following
     # would not work following the previous example:
     #
     #   @group.avatars << Avatar.new   # this would work if User belonged_to Avatar rather than the other way around
@@ -598,7 +616,7 @@ module ActiveRecord
     # === Polymorphic Associations
     #
     # Polymorphic associations on models are not restricted on what types of models they
-    # can be associated with.  Rather, they specify an interface that a +has_many+ association
+    # can be associated with. Rather, they specify an interface that a +has_many+ association
     # must adhere to.
     #
     #   class Asset < ActiveRecord::Base
@@ -612,7 +630,7 @@ module ActiveRecord
     #   @asset.attachable = @post
     #
     # This works by using a type column in addition to a foreign key to specify the associated
-    # record.  In the Asset example, you'd need an +attachable_id+ integer column and an
+    # record. In the Asset example, you'd need an +attachable_id+ integer column and an
     # +attachable_type+ string column.
     #
     # Using polymorphic associations in combination with single table inheritance (STI) is
@@ -668,7 +686,7 @@ module ActiveRecord
     #
     # Consider the following loop using the class above:
     #
-    #   for post in Post.all
+    #   Post.all.each do |post|
     #     puts "Post:            " + post.title
     #     puts "Written by:      " + post.author.name
     #     puts "Last comment on: " + post.comments.first.created_on
@@ -677,7 +695,7 @@ module ActiveRecord
     # To iterate over these one hundred posts, we'll generate 201 database queries. Let's
     # first just optimize it for retrieving the author:
     #
-    #   for post in Post.find(:all, :include => :author)
+    #   Post.includes(:author).each do |post|
     #
     # This references the name of the +belongs_to+ association that also used the <tt>:author</tt>
     # symbol. After loading the posts, find will collect the +author_id+ from each one and load
@@ -686,7 +704,7 @@ module ActiveRecord
     #
     # We can improve upon the situation further by referencing both associations in the finder with:
     #
-    #   for post in Post.find(:all, :include => [ :author, :comments ])
+    #   Post.includes(:author, :comments).each do |post|
     #
     # This will load all comments with a single query. This reduces the total number of queries
     # to 3. More generally the number of queries will be 1 plus the number of associations
@@ -694,7 +712,7 @@ module ActiveRecord
     #
     # To include a deep hierarchy of associations, use a hash:
     #
-    #   for post in Post.find(:all, :include => [ :author, { :comments => { :author => :gravatar } } ])
+    #   Post.includes(:author, {:comments => {:author => :gravatar}}).each do |post|
     #
     # That'll grab not only all the comments but all their authors and gravatar pictures.
     # You can mix and match symbols, arrays and hashes in any combination to describe the
@@ -722,13 +740,13 @@ module ActiveRecord
     # <tt>:order => "author.name DESC"</tt> will work but <tt>:order => "name DESC"</tt> will not.
     #
     # If you do want eager load only some members of an association it is usually more natural
-    # to <tt>:include</tt> an association which has conditions defined on it:
+    # to include an association which has conditions defined on it:
     #
     #   class Post < ActiveRecord::Base
     #     has_many :approved_comments, :class_name => 'Comment', :conditions => ['approved = ?', true]
     #   end
     #
-    #   Post.find(:all, :include => :approved_comments)
+    #   Post.includes(:approved_comments)
     #
     # This will load posts and eager load the +approved_comments+ association, which contains
     # only those comments that have been approved.
@@ -740,10 +758,10 @@ module ActiveRecord
     #     has_many :most_recent_comments, :class_name => 'Comment', :order => 'id DESC', :limit => 10
     #   end
     #
-    #   Picture.first(:include => :most_recent_comments).most_recent_comments # => returns all associated comments.
+    #   Picture.includes(:most_recent_comments).first.most_recent_comments # => returns all associated comments.
     #
     # When eager loaded, conditions are interpolated in the context of the model class, not
-    # the model instance.  Conditions are lazily interpolated before the actual model exists.
+    # the model instance. Conditions are lazily interpolated before the actual model exists.
     #
     # Eager loading is supported with polymorphic associations.
     #
@@ -753,7 +771,7 @@ module ActiveRecord
     #
     # A call that tries to eager load the addressable model
     #
-    #   Address.find(:all, :include => :addressable)
+    #   Address.includes(:addressable)
     #
     # This will execute one query to load the addresses and load the addressables with one
     # query per addressable type.
@@ -767,47 +785,47 @@ module ActiveRecord
     # == Table Aliasing
     #
     # Active Record uses table aliasing in the case that a table is referenced multiple times
-    # in a join.  If a table is referenced only once, the standard table name is used.  The
+    # in a join. If a table is referenced only once, the standard table name is used. The
     # second time, the table is aliased as <tt>#{reflection_name}_#{parent_table_name}</tt>.
     # Indexes are appended for any more successive uses of the table name.
     #
-    #   Post.find :all, :joins => :comments
+    #   Post.joins(:comments)
     #   # => SELECT ... FROM posts INNER JOIN comments ON ...
-    #   Post.find :all, :joins => :special_comments # STI
+    #   Post.joins(:special_comments) # STI
     #   # => SELECT ... FROM posts INNER JOIN comments ON ... AND comments.type = 'SpecialComment'
-    #   Post.find :all, :joins => [:comments, :special_comments] # special_comments is the reflection name, posts is the parent table name
+    #   Post.joins(:comments, :special_comments) # special_comments is the reflection name, posts is the parent table name
     #   # => SELECT ... FROM posts INNER JOIN comments ON ... INNER JOIN comments special_comments_posts
     #
     # Acts as tree example:
     #
-    #   TreeMixin.find :all, :joins => :children
+    #   TreeMixin.joins(:children)
     #   # => SELECT ... FROM mixins INNER JOIN mixins childrens_mixins ...
-    #   TreeMixin.find :all, :joins => {:children => :parent}
+    #   TreeMixin.joins(:children => :parent)
     #   # => SELECT ... FROM mixins INNER JOIN mixins childrens_mixins ...
     #                               INNER JOIN parents_mixins ...
-    #   TreeMixin.find :all, :joins => {:children => {:parent => :children}}
+    #   TreeMixin.joins(:children => {:parent => :children})
     #   # => SELECT ... FROM mixins INNER JOIN mixins childrens_mixins ...
     #                               INNER JOIN parents_mixins ...
     #                               INNER JOIN mixins childrens_mixins_2
     #
     # Has and Belongs to Many join tables use the same idea, but add a <tt>_join</tt> suffix:
     #
-    #   Post.find :all, :joins => :categories
+    #   Post.joins(:categories)
     #   # => SELECT ... FROM posts INNER JOIN categories_posts ... INNER JOIN categories ...
-    #   Post.find :all, :joins => {:categories => :posts}
+    #   Post.joins(:categories => :posts)
     #   # => SELECT ... FROM posts INNER JOIN categories_posts ... INNER JOIN categories ...
     #                              INNER JOIN categories_posts posts_categories_join INNER JOIN posts posts_categories
-    #   Post.find :all, :joins => {:categories => {:posts => :categories}}
+    #   Post.joins(:categories => {:posts => :categories})
     #   # => SELECT ... FROM posts INNER JOIN categories_posts ... INNER JOIN categories ...
     #                              INNER JOIN categories_posts posts_categories_join INNER JOIN posts posts_categories
     #                              INNER JOIN categories_posts categories_posts_join INNER JOIN categories categories_posts_2
     #
-    # If you wish to specify your own custom joins using a <tt>:joins</tt> option, those table
+    # If you wish to specify your own custom joins using <tt>joins</tt> method, those table
     # names will take precedence over the eager associations:
     #
-    #   Post.find :all, :joins => :comments, :joins => "inner join comments ..."
+    #   Post.joins(:comments).joins("inner join comments ...")
     #   # => SELECT ... FROM posts INNER JOIN comments_posts ON ... INNER JOIN comments ...
-    #   Post.find :all, :joins => [:comments, :special_comments], :joins => "inner join comments ..."
+    #   Post.joins(:comments, :special_comments).joins("inner join comments ...")
     #   # => SELECT ... FROM posts INNER JOIN comments comments_posts ON ...
     #                              INNER JOIN comments special_comments_posts ...
     #                              INNER JOIN comments ...
@@ -849,7 +867,7 @@ module ActiveRecord
     # == Bi-directional associations
     #
     # When you specify an association there is usually an association on the associated model
-    # that specifies the same relationship in reverse.  For example, with the following models:
+    # that specifies the same relationship in reverse. For example, with the following models:
     #
     #    class Dungeon < ActiveRecord::Base
     #      has_many :traps
@@ -866,9 +884,9 @@ module ActiveRecord
     #
     # The +traps+ association on +Dungeon+ and the +dungeon+ association on +Trap+ are
     # the inverse of each other and the inverse of the +dungeon+ association on +EvilWizard+
-    # is the +evil_wizard+ association on +Dungeon+ (and vice-versa).  By default,
+    # is the +evil_wizard+ association on +Dungeon+ (and vice-versa). By default,
     # Active Record doesn't know anything about these inverse relationships and so no object
-    # loading optimisation is possible.  For example:
+    # loading optimization is possible. For example:
     #
     #    d = Dungeon.first
     #    t = d.traps.first
@@ -878,8 +896,8 @@ module ActiveRecord
     #
     # The +Dungeon+ instances +d+ and <tt>t.dungeon</tt> in the above example refer to
     # the same object data from the database, but are actually different in-memory copies
-    # of that data.  Specifying the <tt>:inverse_of</tt> option on associations lets you tell
-    # Active Record about inverse relationships and it will optimise object loading.  For
+    # of that data. Specifying the <tt>:inverse_of</tt> option on associations lets you tell
+    # Active Record about inverse relationships and it will optimise object loading. For
     # example, if we changed our model definitions to:
     #
     #    class Dungeon < ActiveRecord::Base
@@ -1039,7 +1057,7 @@ module ActiveRecord
       # === Example
       #
       # Example: A Firm class declares <tt>has_many :clients</tt>, which will add:
-      # * <tt>Firm#clients</tt> (similar to <tt>Clients.find :all, :conditions => ["firm_id = ?", id]</tt>)
+      # * <tt>Firm#clients</tt> (similar to <tt>Clients.all :conditions => ["firm_id = ?", id]</tt>)
       # * <tt>Firm#clients<<</tt>
       # * <tt>Firm#clients.delete</tt>
       # * <tt>Firm#clients=</tt>
@@ -1062,7 +1080,7 @@ module ActiveRecord
       #   specify it with this option.
       # [:conditions]
       #   Specify the conditions that the associated objects must meet in order to be included as a +WHERE+
-      #   SQL fragment, such as <tt>price > 5 AND name LIKE 'B%'</tt>.  Record creations from
+      #   SQL fragment, such as <tt>price > 5 AND name LIKE 'B%'</tt>. Record creations from
       #   the association are scoped if a hash is used.
       #   <tt>has_many :posts, :conditions => {:published => true}</tt> will create published
       #   posts with <tt>@blog.posts.create</tt> or <tt>@blog.posts.build</tt>.
@@ -1077,10 +1095,11 @@ module ActiveRecord
       #   Specify the method that returns the primary key used for the association. By default this is +id+.
       # [:dependent]
       #   If set to <tt>:destroy</tt> all the associated objects are destroyed
-      #   alongside this object by calling their +destroy+ method.  If set to <tt>:delete_all</tt> all associated
-      #   objects are deleted *without* calling their +destroy+ method.  If set to <tt>:nullify</tt> all associated
+      #   alongside this object by calling their +destroy+ method. If set to <tt>:delete_all</tt> all associated
+      #   objects are deleted *without* calling their +destroy+ method. If set to <tt>:nullify</tt> all associated
       #   objects' foreign keys are set to +NULL+ *without* calling their +save+ callbacks. If set to
-      #   <tt>:restrict</tt> this object cannot be deleted if it has any associated object.
+      #   <tt>:restrict</tt> this object raises an <tt>ActiveRecord::DeleteRestrictionError</tt> exception and
+      #   cannot be deleted if it has any associated objects.
       #
       #   If using with the <tt>:through</tt> option, the association on the join model must be
       #   a +belongs_to+, and the records which get deleted are the join records, rather than
@@ -1088,7 +1107,8 @@ module ActiveRecord
       #
       # [:finder_sql]
       #   Specify a complete SQL statement to fetch the association. This is a good way to go for complex
-      #   associations that depend on multiple tables. Note: When this option is used, +find_in_collection+
+      #   associations that depend on multiple tables. May be supplied as a string or a proc where interpolation is
+      #   required. Note: When this option is used, +find_in_collection+
       #   is _not_ added.
       # [:counter_sql]
       #   Specify a complete SQL statement to fetch the size of the association. If <tt>:finder_sql</tt> is
@@ -1163,11 +1183,14 @@ module ActiveRecord
       #   has_many :tags, :as => :taggable
       #   has_many :reports, :readonly => true
       #   has_many :subscribers, :through => :subscriptions, :source => :user
-      #   has_many :subscribers, :class_name => "Person", :finder_sql =>
-      #       'SELECT DISTINCT people.* ' +
-      #       'FROM people p, post_subscriptions ps ' +
-      #       'WHERE ps.post_id = #{id} AND ps.person_id = p.id ' +
-      #       'ORDER BY p.first_name'
+      #   has_many :subscribers, :class_name => "Person", :finder_sql => Proc.new {
+      #       %Q{
+      #         SELECT DISTINCT *
+      #         FROM people p, post_subscriptions ps
+      #         WHERE ps.post_id = #{id} AND ps.person_id = p.id
+      #         ORDER BY p.first_name
+      #       }
+      #   }
       def has_many(name, options = {}, &extension)
         Builder::HasMany.build(self, name, options, &extension)
       end
@@ -1229,7 +1252,8 @@ module ActiveRecord
       #   If set to <tt>:destroy</tt>, the associated object is destroyed when this object is. If set to
       #   <tt>:delete</tt>, the associated object is deleted *without* calling its destroy method.
       #   If set to <tt>:nullify</tt>, the associated object's foreign key is set to +NULL+.
-      #   Also, association is assigned.
+      #   Also, association is assigned. If set to <tt>:restrict</tt> this object raises an
+      #   <tt>ActiveRecord::DeleteRestrictionError</tt> exception and cannot be deleted if it has any associated object.
       # [:foreign_key]
       #   Specify the foreign key used for the association. By default this is guessed to be the name
       #   of this class in lower-case and "_id" suffixed. So a Person class that makes a +has_one+ association
@@ -1245,7 +1269,7 @@ module ActiveRecord
       #   you want to do a join but not include the joined columns. Do not forget to include the
       #   primary and foreign keys, otherwise it will raise an error.
       # [:through]
-      #   Specifies a Join Model through which to perform the query.  Options for <tt>:class_name</tt>,
+      #   Specifies a Join Model through which to perform the query. Options for <tt>:class_name</tt>,
       #   <tt>:primary_key</tt>, and <tt>:foreign_key</tt> are ignored, as the association uses the
       #   source reflection. You can only use a <tt>:through</tt> query through a <tt>has_one</tt>
       #   or <tt>belongs_to</tt> association on the join model.
@@ -1267,7 +1291,7 @@ module ActiveRecord
       #   By default, only save the associated object if it's a new record.
       # [:inverse_of]
       #   Specifies the name of the <tt>belongs_to</tt> association on the associated object
-      #   that is the inverse of this <tt>has_one</tt> association.  Does not work in combination
+      #   that is the inverse of this <tt>has_one</tt> association. Does not work in combination
       #   with <tt>:through</tt> or <tt>:as</tt> options.
       #   See ActiveRecord::Associations::ClassMethods's overview on Bi-directional associations for more detail.
       #
@@ -1325,7 +1349,7 @@ module ActiveRecord
       #
       # [:class_name]
       #   Specify the class name of the association. Use it only if that name can't be inferred
-      #   from the association name. So <tt>has_one :author</tt> will by default be linked to the Author class, but
+      #   from the association name. So <tt>belongs_to :author</tt> will by default be linked to the Author class, but
       #   if the real class name is Person, you'll have to specify it with this option.
       # [:conditions]
       #   Specify the conditions that the associated object must meet in order to be included as a +WHERE+
@@ -1385,7 +1409,7 @@ module ActiveRecord
       #   will be updated with the current time in addition to the updated_at/on attribute.
       # [:inverse_of]
       #   Specifies the name of the <tt>has_one</tt> or <tt>has_many</tt> association on the associated
-      #   object that is the inverse of this <tt>belongs_to</tt> association.  Does not work in
+      #   object that is the inverse of this <tt>belongs_to</tt> association. Does not work in
       #   combination with the <tt>:polymorphic</tt> options.
       #   See ActiveRecord::Associations::ClassMethods's overview on Bi-directional associations for more detail.
       #
@@ -1405,15 +1429,15 @@ module ActiveRecord
       end
 
       # Specifies a many-to-many relationship with another class. This associates two classes via an
-      # intermediate join table.  Unless the join table is explicitly specified as an option, it is
+      # intermediate join table. Unless the join table is explicitly specified as an option, it is
       # guessed using the lexical order of the class names. So a join between Developer and Project
       # will give the default join table name of "developers_projects" because "D" outranks "P".
-      # Note that this precedence is calculated using the <tt><</tt> operator for String.  This
+      # Note that this precedence is calculated using the <tt><</tt> operator for String. This
       # means that if the strings are of different lengths, and the strings are equal when compared
       # up to the shortest length, then the longer string is considered of higher
-      # lexical precedence than the shorter one.  For example, one would expect the tables "paper_boxes" and "papers"
+      # lexical precedence than the shorter one. For example, one would expect the tables "paper_boxes" and "papers"
       # to generate a join table name of "papers_paper_boxes" because of the length of the name "paper_boxes",
-      # but it in fact generates a join table name of "paper_boxes_papers".  Be aware of this caveat, and use the
+      # but it in fact generates a join table name of "paper_boxes_papers". Be aware of this caveat, and use the
       # custom <tt>:join_table</tt> option if you need to.
       #
       # The join table should not have a primary key or a model associated with it. You must manually generate the
@@ -1515,7 +1539,7 @@ module ActiveRecord
       #   the association will use "project_id" as the default <tt>:association_foreign_key</tt>.
       # [:conditions]
       #   Specify the conditions that the associated object must meet in order to be included as a +WHERE+
-      #   SQL fragment, such as <tt>authorized = 1</tt>.  Record creations from the association are
+      #   SQL fragment, such as <tt>authorized = 1</tt>. Record creations from the association are
       #   scoped if a hash is used.
       #   <tt>has_many :posts, :conditions => {:published => true}</tt> will create published posts with <tt>@blog.posts.create</tt>
       #   or <tt>@blog.posts.build</tt>.
@@ -1575,17 +1599,6 @@ module ActiveRecord
       def has_and_belongs_to_many(name, options = {}, &extension)
         Builder::HasAndBelongsToMany.build(self, name, options, &extension)
       end
-
-      protected
-
-      def preload_associations(records, associations, options = {}) #:nodoc:
-        ActiveSupport::Deprecation.warn(
-          "preload_associations(records, associations, options = {}) is deprecated. Use " \
-          "ActiveRecord::Associations::Preloader.new(records, associations, options = {}).run " \
-          "instead."
-        )
-        Preloader.new(records, associations, options).run
-      end
     end
   end
 end