activerecord 4.2.11.3 → 5.0.7.2

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2004-2014 David Heinemeier Hansson
+Copyright (c) 2004-2016 David Heinemeier Hansson
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -17,4 +17,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -26,13 +26,13 @@ The Product class is automatically mapped to the table named "products",
 which might look like this:
 
    CREATE TABLE products (
-     id int(11) NOT NULL auto_increment,
+     id int NOT NULL auto_increment,
      name varchar(255),
      PRIMARY KEY  (id)
    );
 
-This would also define the following accessors: `Product#name` and
-`Product#name=(new_name)`.
+This would also define the following accessors: <tt>Product#name</tt> and
+<tt>Product#name=(new_name)</tt>.
 
 
 * Associations between objects defined by simple class methods.
@@ -125,7 +125,7 @@ This would also define the following accessors: `Product#name` and
     )
 
   {Learn more}[link:classes/ActiveRecord/Base.html] and read about the built-in support for
-  MySQL[link:classes/ActiveRecord/ConnectionAdapters/MysqlAdapter.html],
+  MySQL[link:classes/ActiveRecord/ConnectionAdapters/Mysql2Adapter.html],
   PostgreSQL[link:classes/ActiveRecord/ConnectionAdapters/PostgreSQLAdapter.html], and
   SQLite3[link:classes/ActiveRecord/ConnectionAdapters/SQLite3Adapter.html].
 
@@ -138,7 +138,7 @@ This would also define the following accessors: `Product#name` and
 
 * Database agnostic schema management with Migrations.
 
-    class AddSystemSettings < ActiveRecord::Migration
+    class AddSystemSettings < ActiveRecord::Migration[5.0]
       def up
         create_table :system_settings do |t|
           t.string  :name
@@ -188,11 +188,11 @@ Admit the Database:
 
 The latest version of Active Record can be installed with RubyGems:
 
-  % [sudo] gem install activerecord
+  $ gem install activerecord
 
 Source code can be downloaded as part of the Rails project on GitHub:
 
-* https://github.com/rails/rails/tree/4-2-stable/activerecord
+* https://github.com/rails/rails/tree/5-0-stable/activerecord
 
 
 == License
@@ -215,4 +215,3 @@ Bug reports can be filed for the Ruby on Rails project here:
 Feature requests should be discussed on the rails-core mailing list here:
 
 * https://groups.google.com/forum/?fromgroups#!forum/rubyonrails-core
-

data/examples/performance.rb

@@ -1,4 +1,3 @@
-require File.expand_path('../../../load_paths', __FILE__)
 require "active_record"
 require 'benchmark/ips'
 
@@ -39,8 +38,8 @@ class Exhibit < ActiveRecord::Base
     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
+  def self.look(exhibits) exhibits.each(&:look) end
+  def self.feel(exhibits) exhibits.each(&:feel) end
 end
 
 def progress_bar(int); print "." if (int%100).zero? ; end

data/examples/simple.rb

@@ -1,4 +1,3 @@
-require File.expand_path('../../../load_paths', __FILE__)
 require 'active_record'
 
 class Person < ActiveRecord::Base

data/lib/active_record.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2004-2014 David Heinemeier Hansson
+# Copyright (c) 2004-2016 David Heinemeier Hansson
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -40,6 +40,7 @@ module ActiveRecord
   autoload :CounterCache
   autoload :DynamicMatchers
   autoload :Enum
+  autoload :InternalMetadata
   autoload :Explain
   autoload :Inheritance
   autoload :Integration
@@ -48,9 +49,11 @@ module ActiveRecord
   autoload :ModelSchema
   autoload :NestedAttributes
   autoload :NoTouching
+  autoload :TouchLater
   autoload :Persistence
   autoload :QueryCache
   autoload :Querying
+  autoload :CollectionCacheKey
   autoload :ReadonlyAttributes
   autoload :RecordInvalid, 'active_record/validations'
   autoload :Reflection
@@ -63,10 +66,12 @@ module ActiveRecord
   autoload :Serialization
   autoload :StatementCache
   autoload :Store
+  autoload :Suppressor
   autoload :Timestamp
   autoload :Transactions
   autoload :Translation
   autoload :Validations
+  autoload :SecureToken
 
   eager_autoload do
     autoload :ActiveRecordError, 'active_record/errors'
@@ -96,6 +101,7 @@ module ActiveRecord
     end
 
     autoload :Result
+    autoload :TableMetadata
   end
 
   module Coders
@@ -132,7 +138,6 @@ module ActiveRecord
 
     eager_autoload do
       autoload :AbstractAdapter
-      autoload :ConnectionManagement, "active_record/connection_adapters/abstract/connection_pool"
     end
   end
 

data/lib/active_record/aggregations.rb

@@ -1,14 +1,31 @@
 module ActiveRecord
-  # = Active Record Aggregations
-  module Aggregations # :nodoc:
+  # See ActiveRecord::Aggregations::ClassMethods for documentation
+  module Aggregations
     extend ActiveSupport::Concern
 
-    def clear_aggregation_cache #:nodoc:
-      @aggregation_cache.clear if persisted?
+    def initialize_dup(*) # :nodoc:
+      @aggregation_cache = {}
+      super
     end
 
-    # Active Record implements aggregation through a macro-like class method called +composed_of+
-    # for representing attributes  as value objects. It expresses relationships like "Account [is]
+    def reload(*) # :nodoc:
+      clear_aggregation_cache
+      super
+    end
+
+    private
+
+      def clear_aggregation_cache # :nodoc:
+        @aggregation_cache.clear if persisted?
+      end
+
+      def init_internals # :nodoc:
+        @aggregation_cache = {}
+        super
+      end
+
+    # Active Record implements aggregation through a macro-like class method called #composed_of
+    # for representing attributes as value objects. It expresses relationships like "Account [is]
     # composed of Money [among other things]" or "Person [is] composed of [an] address". Each call
     # to the macro adds a description of how the value objects are created from the attributes of
     # the entity object (when the entity is initialized either as a new object or from finding an
@@ -16,7 +33,7 @@ module ActiveRecord
     # the database).
     #
     #   class Customer < ActiveRecord::Base
-    #     composed_of :balance, class_name: "Money", mapping: %w(balance amount)
+    #     composed_of :balance, class_name: "Money", mapping: %w(amount currency)
     #     composed_of :address, mapping: [ %w(address_street street), %w(address_city city) ]
     #   end
     #
@@ -87,11 +104,6 @@ module ActiveRecord
     #   customer.address_city   = "Copenhagen"
     #   customer.address        # => Address.new("Hyancintvej", "Copenhagen")
     #
-    #   customer.address_street = "Vesterbrogade"
-    #   customer.address        # => Address.new("Hyancintvej", "Copenhagen")
-    #   customer.clear_aggregation_cache
-    #   customer.address        # => Address.new("Vesterbrogade", "Copenhagen")
-    #
     #   customer.address = Address.new("May Street", "Chicago")
     #   customer.address_street # => "May Street"
     #   customer.address_city   # => "Chicago"
@@ -108,12 +120,12 @@ module ActiveRecord
     #
     # It's also important to treat the value objects as immutable. Don't allow the Money object to have
     # its amount changed after creation. Create a new Money object with the new value instead. The
-    # Money#exchange_to method is an example of this. It returns a new value object instead of changing
+    # <tt>Money#exchange_to</tt> method is an example of this. It returns a new value object instead of changing
     # its own values. Active Record won't persist value objects that have been changed through means
     # other than the writer method.
     #
     # The immutable requirement is enforced by Active Record by freezing any object assigned as a value
-    # object. Attempting to change it afterwards will result in a RuntimeError.
+    # object. Attempting to change it afterwards will result in a +RuntimeError+.
     #
     # Read more about value objects on http://c2.com/cgi/wiki?ValueObject and on the dangers of not
     # keeping value objects immutable on http://c2.com/cgi/wiki?ValueObjectsShouldBeImmutable
@@ -122,17 +134,17 @@ module ActiveRecord
     #
     # By default value objects are initialized by calling the <tt>new</tt> constructor of the value
     # class passing each of the mapped attributes, in the order specified by the <tt>:mapping</tt>
-    # option, as arguments. If the value class doesn't support this convention then +composed_of+ allows
+    # option, as arguments. If the value class doesn't support this convention then #composed_of allows
     # a custom constructor to be specified.
     #
     # When a new value is assigned to the value object, the default assumption is that the new value
     # is an instance of the value class. Specifying a custom converter allows the new value to be automatically
     # converted to an instance of value class if necessary.
     #
-    # For example, the NetworkResource model has +network_address+ and +cidr_range+ attributes that should be
-    # aggregated using the NetAddr::CIDR value class (http://www.ruby-doc.org/gems/docs/n/netaddr-1.5.0/NetAddr/CIDR.html).
+    # For example, the +NetworkResource+ model has +network_address+ and +cidr_range+ attributes that should be
+    # aggregated using the +NetAddr::CIDR+ value class (http://www.rubydoc.info/gems/netaddr/1.5.0/NetAddr/CIDR).
     # The constructor for the value class is called +create+ and it expects a CIDR address string as a parameter.
-    # New values can be assigned to the value object using either another NetAddr::CIDR object, a string
+    # New values can be assigned to the value object using either another +NetAddr::CIDR+ object, a string
     # or an array. The <tt>:constructor</tt> and <tt>:converter</tt> options can be used to meet
     # these requirements:
     #
@@ -161,7 +173,7 @@ module ActiveRecord
     #
     # == Finding records by a value object
     #
-    # Once a +composed_of+ relationship is specified for a model, records can be loaded from the database
+    # Once a #composed_of relationship is specified for a model, records can be loaded from the database
     # by specifying an instance of the value object in the conditions hash. The following example
     # finds all customers with +balance_amount+ equal to 20 and +balance_currency+ equal to "USD":
     #
@@ -174,7 +186,7 @@ module ActiveRecord
       # Options are:
       # * <tt>:class_name</tt> - Specifies the class name of the association. Use it only if that name
       #   can't be inferred from the part id. So <tt>composed_of :address</tt> will by default be linked
-      #   to the Address class, but if the real class name is CompanyAddress, you'll have to specify it
+      #   to the Address class, but if the real class name is +CompanyAddress+, you'll have to specify it
       #   with this option.
       # * <tt>:mapping</tt> - Specifies the mapping of entity attributes to attributes of the value
       #   object. Each mapping is represented as an array where the first item is the name of the
@@ -252,7 +264,8 @@ module ActiveRecord
             hash_from_multiparameter_assignment = part.is_a?(Hash) &&
               part.each_key.all? { |k| k.is_a?(Integer) }
             if hash_from_multiparameter_assignment
-              part = klass.new(*part.values)
+              raise ArgumentError unless part.size == part.each_key.max
+              part = klass.new(*part.sort.map(&:last))
             end
 
             if part.nil? && allow_nil

data/lib/active_record/association_relation.rb

@@ -1,7 +1,7 @@
 module ActiveRecord
   class AssociationRelation < Relation
-    def initialize(klass, table, association)
-      super(klass, table)
+    def initialize(klass, table, predicate_builder, association)
+      super(klass, table, predicate_builder)
       @association = association
     end
 
@@ -10,7 +10,7 @@ module ActiveRecord
     end
 
     def ==(other)
-      other == to_a
+      other == records
     end
 
     def build(*args, &block)
@@ -29,7 +29,10 @@ module ActiveRecord
     private
 
     def exec_queries
-      super.each { |r| @association.set_inverse_instance r }
+      super do |r|
+        @association.set_inverse_instance r
+        yield r if block_given?
+      end
     end
   end
 end

data/lib/active_record/associations.rb

@@ -5,95 +5,170 @@ require 'active_record/errors'
 
 module ActiveRecord
   class AssociationNotFoundError < ConfigurationError #:nodoc:
-    def initialize(record, association_name)
-      super("Association named '#{association_name}' was not found on #{record.class.name}; perhaps you misspelled it?")
+    def initialize(record = nil, association_name = nil)
+      if record && association_name
+        super("Association named '#{association_name}' was not found on #{record.class.name}; perhaps you misspelled it?")
+      else
+        super("Association was not found.")
+      end
     end
   end
 
   class InverseOfAssociationNotFoundError < ActiveRecordError #:nodoc:
-    def initialize(reflection, associated_class = nil)
-      super("Could not find the inverse association for #{reflection.name} (#{reflection.options[:inverse_of].inspect} in #{associated_class.nil? ? reflection.class_name : associated_class.name})")
+    def initialize(reflection = nil, associated_class = nil)
+      if reflection
+        super("Could not find the inverse association for #{reflection.name} (#{reflection.options[:inverse_of].inspect} in #{associated_class.nil? ? reflection.class_name : associated_class.name})")
+      else
+        super("Could not find the inverse association.")
+      end
     end
   end
 
   class HasManyThroughAssociationNotFoundError < ActiveRecordError #:nodoc:
-    def initialize(owner_class_name, reflection)
-      super("Could not find the association #{reflection.options[:through].inspect} in model #{owner_class_name}")
+    def initialize(owner_class_name = nil, reflection = nil)
+      if owner_class_name && reflection
+        super("Could not find the association #{reflection.options[:through].inspect} in model #{owner_class_name}")
+      else
+        super("Could not find the association.")
+      end
     end
   end
 
   class HasManyThroughAssociationPolymorphicSourceError < ActiveRecordError #:nodoc:
-    def initialize(owner_class_name, reflection, source_reflection)
-      super("Cannot have a has_many :through association '#{owner_class_name}##{reflection.name}' on the polymorphic object '#{source_reflection.class_name}##{source_reflection.name}' without 'source_type'. Try adding 'source_type: \"#{reflection.name.to_s.classify}\"' to 'has_many :through' definition.")
+    def initialize(owner_class_name = nil, reflection = nil, source_reflection = nil)
+      if owner_class_name && reflection && source_reflection
+        super("Cannot have a has_many :through association '#{owner_class_name}##{reflection.name}' on the polymorphic object '#{source_reflection.class_name}##{source_reflection.name}' without 'source_type'. Try adding 'source_type: \"#{reflection.name.to_s.classify}\"' to 'has_many :through' definition.")
+      else
+        super("Cannot have a has_many :through association.")
+      end
     end
   end
 
   class HasManyThroughAssociationPolymorphicThroughError < ActiveRecordError #:nodoc:
-    def initialize(owner_class_name, reflection)
-      super("Cannot have a has_many :through association '#{owner_class_name}##{reflection.name}' which goes through the polymorphic association '#{owner_class_name}##{reflection.through_reflection.name}'.")
+    def initialize(owner_class_name = nil, reflection = nil)
+      if owner_class_name && reflection
+        super("Cannot have a has_many :through association '#{owner_class_name}##{reflection.name}' which goes through the polymorphic association '#{owner_class_name}##{reflection.through_reflection.name}'.")
+      else
+        super("Cannot have a has_many :through association.")
+      end
     end
   end
 
   class HasManyThroughAssociationPointlessSourceTypeError < ActiveRecordError #:nodoc:
-    def initialize(owner_class_name, reflection, source_reflection)
-      super("Cannot have a has_many :through association '#{owner_class_name}##{reflection.name}' with a :source_type option if the '#{reflection.through_reflection.class_name}##{source_reflection.name}' is not polymorphic. Try removing :source_type on your association.")
+    def initialize(owner_class_name = nil, reflection = nil, source_reflection = nil)
+      if owner_class_name && reflection && source_reflection
+        super("Cannot have a has_many :through association '#{owner_class_name}##{reflection.name}' with a :source_type option if the '#{reflection.through_reflection.class_name}##{source_reflection.name}' is not polymorphic. Try removing :source_type on your association.")
+      else
+        super("Cannot have a has_many :through association.")
+      end
     end
   end
 
   class HasOneThroughCantAssociateThroughCollection < ActiveRecordError #:nodoc:
-    def initialize(owner_class_name, reflection, through_reflection)
-      super("Cannot have a has_one :through association '#{owner_class_name}##{reflection.name}' where the :through association '#{owner_class_name}##{through_reflection.name}' is a collection. Specify a has_one or belongs_to association in the :through option instead.")
+    def initialize(owner_class_name = nil, reflection = nil, through_reflection = nil)
+      if owner_class_name && reflection && through_reflection
+        super("Cannot have a has_one :through association '#{owner_class_name}##{reflection.name}' where the :through association '#{owner_class_name}##{through_reflection.name}' is a collection. Specify a has_one or belongs_to association in the :through option instead.")
+      else
+        super("Cannot have a has_one :through association.")
+      end
     end
   end
 
   class HasOneAssociationPolymorphicThroughError < ActiveRecordError #:nodoc:
-    def initialize(owner_class_name, reflection)
-      super("Cannot have a has_one :through association '#{owner_class_name}##{reflection.name}' which goes through the polymorphic association '#{owner_class_name}##{reflection.through_reflection.name}'.")
+    def initialize(owner_class_name = nil, reflection = nil)
+      if owner_class_name && reflection
+        super("Cannot have a has_one :through association '#{owner_class_name}##{reflection.name}' which goes through the polymorphic association '#{owner_class_name}##{reflection.through_reflection.name}'.")
+      else
+        super("Cannot have a has_one :through association.")
+      end
     end
   end
 
   class HasManyThroughSourceAssociationNotFoundError < ActiveRecordError #:nodoc:
-    def initialize(reflection)
-      through_reflection      = reflection.through_reflection
-      source_reflection_names = reflection.source_reflection_names
-      source_associations     = reflection.through_reflection.klass._reflections.keys
-      super("Could not find the source association(s) #{source_reflection_names.collect{ |a| a.inspect }.to_sentence(:two_words_connector => ' or ', :last_word_connector => ', or ', :locale => :en)} in model #{through_reflection.klass}. Try 'has_many #{reflection.name.inspect}, :through => #{through_reflection.name.inspect}, :source => <name>'. Is it one of #{source_associations.to_sentence(:two_words_connector => ' or ', :last_word_connector => ', or ', :locale => :en)}?")
+    def initialize(reflection = nil)
+      if reflection
+        through_reflection      = reflection.through_reflection
+        source_reflection_names = reflection.source_reflection_names
+        source_associations     = reflection.through_reflection.klass._reflections.keys
+        super("Could not find the source association(s) #{source_reflection_names.collect(&:inspect).to_sentence(:two_words_connector => ' or ', :last_word_connector => ', or ', :locale => :en)} in model #{through_reflection.klass}. Try 'has_many #{reflection.name.inspect}, :through => #{through_reflection.name.inspect}, :source => <name>'. Is it one of #{source_associations.to_sentence(:two_words_connector => ' or ', :last_word_connector => ', or ', :locale => :en)}?")
+      else
+        super("Could not find the source association(s).")
+      end
     end
   end
 
-  class HasManyThroughCantAssociateThroughHasOneOrManyReflection < ActiveRecordError #:nodoc:
-    def initialize(owner, reflection)
-      super("Cannot modify association '#{owner.class.name}##{reflection.name}' because the source reflection class '#{reflection.source_reflection.class_name}' is associated to '#{reflection.through_reflection.class_name}' via :#{reflection.source_reflection.macro}.")
+  class ThroughCantAssociateThroughHasOneOrManyReflection < ActiveRecordError #:nodoc:
+    def initialize(owner = nil, reflection = nil)
+      if owner && reflection
+        super("Cannot modify association '#{owner.class.name}##{reflection.name}' because the source reflection class '#{reflection.source_reflection.class_name}' is associated to '#{reflection.through_reflection.class_name}' via :#{reflection.source_reflection.macro}.")
+      else
+        super("Cannot modify association.")
+      end
     end
   end
 
+  class HasManyThroughCantAssociateThroughHasOneOrManyReflection < ThroughCantAssociateThroughHasOneOrManyReflection #:nodoc:
+  end
+
+  class HasOneThroughCantAssociateThroughHasOneOrManyReflection < ThroughCantAssociateThroughHasOneOrManyReflection #:nodoc:
+  end
+
   class HasManyThroughCantAssociateNewRecords < ActiveRecordError #:nodoc:
-    def initialize(owner, reflection)
-      super("Cannot associate new records through '#{owner.class.name}##{reflection.name}' on '#{reflection.source_reflection.class_name rescue nil}##{reflection.source_reflection.name rescue nil}'. Both records must have an id in order to create the has_many :through record associating them.")
+    def initialize(owner = nil, reflection = nil)
+      if owner && reflection
+        super("Cannot associate new records through '#{owner.class.name}##{reflection.name}' on '#{reflection.source_reflection.class_name rescue nil}##{reflection.source_reflection.name rescue nil}'. Both records must have an id in order to create the has_many :through record associating them.")
+      else
+        super("Cannot associate new records.")
+      end
     end
   end
 
   class HasManyThroughCantDissociateNewRecords < ActiveRecordError #:nodoc:
-    def initialize(owner, reflection)
-      super("Cannot dissociate new records through '#{owner.class.name}##{reflection.name}' on '#{reflection.source_reflection.class_name rescue nil}##{reflection.source_reflection.name rescue nil}'. Both records must have an id in order to delete the has_many :through record associating them.")
+    def initialize(owner = nil, reflection = nil)
+      if owner && reflection
+        super("Cannot dissociate new records through '#{owner.class.name}##{reflection.name}' on '#{reflection.source_reflection.class_name rescue nil}##{reflection.source_reflection.name rescue nil}'. Both records must have an id in order to delete the has_many :through record associating them.")
+      else
+        super("Cannot dissociate new records.")
+      end
     end
   end
 
-  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.")
+  class ThroughNestedAssociationsAreReadonly < ActiveRecordError #:nodoc:
+    def initialize(owner = nil, reflection = nil)
+      if owner && reflection
+        super("Cannot modify association '#{owner.class.name}##{reflection.name}' because it goes through more than one other association.")
+      else
+        super("Through nested associations are read-only.")
+      end
     end
   end
 
-  class EagerLoadPolymorphicError < ActiveRecordError #:nodoc:
-    def initialize(reflection)
-      super("Cannot eagerly load the polymorphic association #{reflection.name.inspect}")
+  class HasManyThroughNestedAssociationsAreReadonly < ThroughNestedAssociationsAreReadonly #:nodoc:
+  end
+
+  class HasOneThroughNestedAssociationsAreReadonly < ThroughNestedAssociationsAreReadonly #:nodoc:
+  end
+
+  # This error is raised when trying to eager load a polymorphic association using a JOIN.
+  # Eager loading polymorphic associations is only possible with
+  # {ActiveRecord::Relation#preload}[rdoc-ref:QueryMethods#preload].
+  class EagerLoadPolymorphicError < ActiveRecordError
+    def initialize(reflection = nil)
+      if reflection
+        super("Cannot eagerly load the polymorphic association #{reflection.name.inspect}")
+      else
+        super("Eager load polymorphic error.")
+      end
     end
   end
 
   class ReadOnlyAssociation < ActiveRecordError #:nodoc:
-    def initialize(reflection)
-      super("Cannot add to a has_many :through association. Try adding to #{reflection.through_reflection.name.inspect}.")
+    def initialize(reflection = nil)
+      if reflection
+        super("Cannot add to a has_many :through association. Try adding to #{reflection.through_reflection.name.inspect}.")
+      else
+        super("Read-only reflection error.")
+      end
     end
   end
 
@@ -101,8 +176,12 @@ module ActiveRecord
   # (has_many, has_one) when there is at least 1 child associated instance.
   # ex: if @project.tasks.size > 0, DeleteRestrictionError will be raised when trying to destroy @project
   class DeleteRestrictionError < ActiveRecordError #:nodoc:
-    def initialize(name)
-      super("Cannot delete record because of dependent #{name}")
+    def initialize(name = nil)
+      if name
+        super("Cannot delete record because of dependent #{name}")
+      else
+        super("Delete restriction error.")
+      end
     end
   end
 
@@ -113,19 +192,12 @@ module ActiveRecord
 
     # These classes will be loaded when associations are created.
     # So there is no need to eager load them.
-    autoload :Association,           'active_record/associations/association'
-    autoload :SingularAssociation,   'active_record/associations/singular_association'
-    autoload :CollectionAssociation, 'active_record/associations/collection_association'
-    autoload :ForeignAssociation,    'active_record/associations/foreign_association'
-    autoload :CollectionProxy,       'active_record/associations/collection_proxy'
-
-    autoload :BelongsToAssociation,            'active_record/associations/belongs_to_association'
-    autoload :BelongsToPolymorphicAssociation, 'active_record/associations/belongs_to_polymorphic_association'
-    autoload :HasManyAssociation,              'active_record/associations/has_many_association'
-    autoload :HasManyThroughAssociation,       'active_record/associations/has_many_through_association'
-    autoload :HasOneAssociation,               'active_record/associations/has_one_association'
-    autoload :HasOneThroughAssociation,        'active_record/associations/has_one_through_association'
-    autoload :ThroughAssociation,              'active_record/associations/through_association'
+    autoload :Association
+    autoload :SingularAssociation
+    autoload :CollectionAssociation
+    autoload :ForeignAssociation
+    autoload :CollectionProxy
+    autoload :ThroughAssociation
 
     module Builder #:nodoc:
       autoload :Association,           'active_record/associations/builder/association'
@@ -139,26 +211,32 @@ module ActiveRecord
     end
 
     eager_autoload do
-      autoload :Preloader,        'active_record/associations/preloader'
-      autoload :JoinDependency,   'active_record/associations/join_dependency'
-      autoload :AssociationScope, 'active_record/associations/association_scope'
-      autoload :AliasTracker,     'active_record/associations/alias_tracker'
-    end
+      autoload :BelongsToAssociation
+      autoload :BelongsToPolymorphicAssociation
+      autoload :HasManyAssociation
+      autoload :HasManyThroughAssociation
+      autoload :HasOneAssociation
+      autoload :HasOneThroughAssociation
 
-    # Clears out the association cache.
-    def clear_association_cache #:nodoc:
-      @association_cache.clear if persisted?
+      autoload :Preloader
+      autoload :JoinDependency
+      autoload :AssociationScope
+      autoload :AliasTracker
     end
 
-    # :nodoc:
-    attr_reader :association_cache
+    def self.eager_load!
+      super
+      Preloader.eager_load!
+    end
 
     # Returns the association instance for the given name, instantiating it if it doesn't already exist
     def association(name) #:nodoc:
       association = association_instance_get(name)
 
       if association.nil?
-        raise AssociationNotFoundError.new(self, name) unless reflection = self.class._reflect_on_association(name)
+        unless reflection = self.class._reflect_on_association(name)
+          raise AssociationNotFoundError.new(self, name)
+        end
         association = reflection.association_class.new(self, reflection)
         association_instance_set(name, association)
       end
@@ -166,8 +244,32 @@ module ActiveRecord
       association
     end
 
+    def association_cached?(name) # :nodoc
+      @association_cache.key?(name)
+    end
+
+    def initialize_dup(*) # :nodoc:
+      @association_cache = {}
+      super
+    end
+
+    def reload(*) # :nodoc:
+      clear_association_cache
+      super
+    end
+
     private
-      # Returns the specified association instance if it responds to :loaded?, nil otherwise.
+      # Clears out the association cache.
+      def clear_association_cache # :nodoc:
+        @association_cache.clear if persisted?
+      end
+
+      def init_internals # :nodoc:
+        @association_cache = {}
+        super
+      end
+
+      # Returns the specified association instance if it exists, nil otherwise.
       def association_instance_get(name)
         @association_cache[name]
       end
@@ -204,7 +306,7 @@ module ActiveRecord
     # === A word of warning
     #
     # Don't create associations that have the same name as instance methods of
-    # <tt>ActiveRecord::Base</tt>. Since the association adds a method with that name to
+    # ActiveRecord::Base. Since the association adds a method with that name to
     # its model, it will override the inherited method and break things.
     # For instance, +attributes+ and +connection+ would be bad choices for association names.
     #
@@ -215,17 +317,18 @@ module ActiveRecord
     #                                     |            |  belongs_to  |
     #   generated methods                 | belongs_to | :polymorphic | has_one
     #   ----------------------------------+------------+--------------+---------
-    #   other(force_reload=false)         |     X      |      X       |    X
+    #   other                             |     X      |      X       |    X
     #   other=(other)                     |     X      |      X       |    X
     #   build_other(attributes={})        |     X      |              |    X
     #   create_other(attributes={})       |     X      |              |    X
     #   create_other!(attributes={})      |     X      |              |    X
+    #   reload_other                      |     X      |      X       |    X
     #
-    # ===Collection associations (one-to-many / many-to-many)
+    # === Collection associations (one-to-many / many-to-many)
     #                                     |       |          | has_many
     #   generated methods                 | habtm | has_many | :through
     #   ----------------------------------+-------+----------+----------
-    #   others(force_reload=false)        |   X   |    X     |    X
+    #   others                            |   X   |    X     |    X
     #   others=(other,other,...)          |   X   |    X     |    X
     #   other_ids                         |   X   |    X     |    X
     #   other_ids=(id,id,...)             |   X   |    X     |    X
@@ -248,8 +351,8 @@ module ActiveRecord
     #   others.find(*args)                |   X   |    X     |    X
     #   others.exists?                    |   X   |    X     |    X
     #   others.distinct                   |   X   |    X     |    X
-    #   others.uniq                       |   X   |    X     |    X
     #   others.reset                      |   X   |    X     |    X
+    #   others.reload                     |   X   |    X     |    X
     #
     # === Overriding generated methods
     #
@@ -267,7 +370,7 @@ module ActiveRecord
     #   end
     #
     # If your model class is <tt>Project</tt>, the module is
-    # named <tt>Project::GeneratedFeatureMethods</tt>. The GeneratedFeatureMethods module is
+    # named <tt>Project::GeneratedAssociationMethods</tt>. The +GeneratedAssociationMethods+ 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.
     #
@@ -275,12 +378,12 @@ module ActiveRecord
     #
     # Active Record associations can be used to describe one-to-one, one-to-many and many-to-many
     # relationships between models. Each model uses an association to describe its role in
-    # the relation. The +belongs_to+ association is always used in the model that has
+    # the relation. The #belongs_to association is always used in the model that has
     # the foreign key.
     #
     # === One-to-one
     #
-    # Use +has_one+ in the base, and +belongs_to+ in the associated model.
+    # Use #has_one in the base, and #belongs_to in the associated model.
     #
     #   class Employee < ActiveRecord::Base
     #     has_one :office
@@ -291,7 +394,7 @@ module ActiveRecord
     #
     # === One-to-many
     #
-    # Use +has_many+ in the base, and +belongs_to+ in the associated model.
+    # Use #has_many in the base, and #belongs_to in the associated model.
     #
     #   class Manager < ActiveRecord::Base
     #     has_many :employees
@@ -304,7 +407,7 @@ module ActiveRecord
     #
     # There are two ways to build a many-to-many relationship.
     #
-    # The first way uses a +has_many+ association with the <tt>:through</tt> option and a join model, so
+    # The first way uses a #has_many association with the <tt>:through</tt> option and a join model, so
     # there are two stages of associations.
     #
     #   class Assignment < ActiveRecord::Base
@@ -320,7 +423,7 @@ module ActiveRecord
     #     has_many :programmers, through: :assignments
     #   end
     #
-    # For the second way, use +has_and_belongs_to_many+ in both models. This requires a join table
+    # For the second way, use #has_and_belongs_to_many in both models. This requires a join table
     # that has no corresponding model or primary key.
     #
     #   class Programmer < ActiveRecord::Base
@@ -332,13 +435,13 @@ module ActiveRecord
     #
     # Choosing which way to build a many-to-many relationship is not always simple.
     # If you need to work with the relationship model as its own entity,
-    # use <tt>has_many :through</tt>. Use +has_and_belongs_to_many+ when working with legacy schemas or when
+    # use #has_many <tt>:through</tt>. Use #has_and_belongs_to_many when working with legacy schemas or when
     # you never work directly with the relationship itself.
     #
-    # == Is it a +belongs_to+ or +has_one+ association?
+    # == Is it a #belongs_to or #has_one association?
     #
     # Both express a 1-1 relationship. The difference is mostly where to place the foreign
-    # key, which goes on the table for the class declaring the +belongs_to+ relationship.
+    # key, which goes on the table for the class declaring the #belongs_to relationship.
     #
     #   class User < ActiveRecord::Base
     #     # I reference an account.
@@ -353,14 +456,14 @@ module ActiveRecord
     # The tables for these classes could look something like:
     #
     #   CREATE TABLE users (
-    #     id int(11) NOT NULL auto_increment,
-    #     account_id int(11) default NULL,
+    #     id int NOT NULL auto_increment,
+    #     account_id int default NULL,
     #     name varchar default NULL,
     #     PRIMARY KEY  (id)
     #   )
     #
     #   CREATE TABLE accounts (
-    #     id int(11) NOT NULL auto_increment,
+    #     id int NOT NULL auto_increment,
     #     name varchar default NULL,
     #     PRIMARY KEY  (id)
     #   )
@@ -371,35 +474,35 @@ module ActiveRecord
     # there is some special behavior you should be aware of, mostly involving the saving of
     # associated objects.
     #
-    # You can set the <tt>:autosave</tt> option on a <tt>has_one</tt>, <tt>belongs_to</tt>,
-    # <tt>has_many</tt>, or <tt>has_and_belongs_to_many</tt> association. Setting it
+    # You can set the <tt>:autosave</tt> option on a #has_one, #belongs_to,
+    # #has_many, or #has_and_belongs_to_many association. Setting it
     # to +true+ will _always_ save the members, whereas setting it to +false+ will
     # _never_ save the members. More details about <tt>:autosave</tt> option is available at
     # AutosaveAssociation.
     #
     # === One-to-one associations
     #
-    # * Assigning an object to a +has_one+ association automatically saves that object and
+    # * Assigning an object to a #has_one association automatically saves that object and
     #   the object being replaced (if there is one), in order to update their foreign
     #   keys - except if the parent object is unsaved (<tt>new_record? == true</tt>).
     # * If either of these saves fail (due to one of the objects being invalid), an
-    #   <tt>ActiveRecord::RecordNotSaved</tt> exception is raised and the assignment is
+    #   ActiveRecord::RecordNotSaved exception is raised and the assignment is
     #   cancelled.
-    # * If you wish to assign an object to a +has_one+ association without saving it,
-    #   use the <tt>build_association</tt> method (documented below). The object being
+    # * If you wish to assign an object to a #has_one association without saving it,
+    #   use the <tt>#build_association</tt> method (documented below). The object being
     #   replaced will still be saved to update its foreign key.
-    # * Assigning an object to a +belongs_to+ association does not save the object, since
+    # * Assigning an object to a #belongs_to association does not save the object, since
     #   the foreign key field belongs on the parent. It does not save the parent either.
     #
     # === Collections
     #
-    # * Adding an object to a collection (+has_many+ or +has_and_belongs_to_many+) automatically
+    # * Adding an object to a collection (#has_many or #has_and_belongs_to_many) automatically
     #   saves that object, except if the parent object (the owner of the collection) is not yet
     #   stored in the database.
     # * If saving any of the objects being added to a collection (via <tt>push</tt> or similar)
     #   fails, then <tt>push</tt> returns +false+.
     # * If saving fails while replacing the collection (via <tt>association=</tt>), an
-    #   <tt>ActiveRecord::RecordNotSaved</tt> exception is raised and the assignment is
+    #   ActiveRecord::RecordNotSaved exception is raised and the assignment is
     #   cancelled.
     # * You can add an object to a collection without automatically saving it by using the
     #   <tt>collection.build</tt> method (documented below).
@@ -408,14 +511,14 @@ module ActiveRecord
     #
     # == Customizing the query
     #
-    # \Associations are built from <tt>Relation</tt>s, and you can use the <tt>Relation</tt> syntax
+    # \Associations are built from <tt>Relation</tt> objects, and you can use the Relation syntax
     # to customize them. For example, to add a condition:
     #
     #   class Blog < ActiveRecord::Base
-    #     has_many :published_posts, -> { where published: true }, class_name: 'Post'
+    #     has_many :published_posts, -> { where(published: true) }, class_name: 'Post'
     #   end
     #
-    # Inside the <tt>-> { ... }</tt> block you can use all of the usual <tt>Relation</tt> methods.
+    # Inside the <tt>-> { ... }</tt> block you can use all of the usual Relation methods.
     #
     # === Accessing the owner object
     #
@@ -424,7 +527,7 @@ module ActiveRecord
     # events that occur on the user's birthday:
     #
     #   class User < ActiveRecord::Base
-    #     has_many :birthday_events, ->(user) { where starts_on: user.birthday }, class_name: 'Event'
+    #     has_many :birthday_events, ->(user) { where(starts_on: user.birthday) }, class_name: 'Event'
     #   end
     #
     # Note: Joining, eager loading and preloading of these associations is not fully possible.
@@ -503,8 +606,8 @@ module ActiveRecord
     #
     # * <tt>record.association(:items).owner</tt> - Returns the object the association is part of.
     # * <tt>record.association(:items).reflection</tt> - Returns the reflection object that describes the association.
-    # * <tt>record.association(:items).target</tt> - Returns the associated object for +belongs_to+ and +has_one+, or
-    #   the collection of associated objects for +has_many+ and +has_and_belongs_to_many+.
+    # * <tt>record.association(:items).target</tt> - Returns the associated object for #belongs_to and #has_one, or
+    #   the collection of associated objects for #has_many and #has_and_belongs_to_many.
     #
     # However, inside the actual extension code, you will not have access to the <tt>record</tt> as
     # above. In this case, you can access <tt>proxy_association</tt>. For example,
@@ -516,7 +619,7 @@ module ActiveRecord
     #
     # 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,
+    # #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
@@ -533,7 +636,7 @@ module ActiveRecord
     #   @author.authorships.collect { |a| a.book } # selects all books that the author's authorships belong to
     #   @author.books                              # selects all books by using the Authorship join model
     #
-    # You can also go through a +has_many+ association on the join model:
+    # You can also go through a #has_many association on the join model:
     #
     #   class Firm < ActiveRecord::Base
     #     has_many   :clients
@@ -553,7 +656,7 @@ module ActiveRecord
     #   @firm.clients.flat_map { |c| c.invoices } # select all invoices for all clients of the firm
     #   @firm.invoices                            # selects all invoices by going through the Client join model
     #
-    # Similarly you can go through a +has_one+ association on the join model:
+    # Similarly you can go through a #has_one association on the join model:
     #
     #   class Group < ActiveRecord::Base
     #     has_many   :users
@@ -573,7 +676,7 @@ module ActiveRecord
     #   @group.users.collect { |u| u.avatar }.compact # select all avatars for all users in the group
     #   @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
+    # 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
     # would not work following the previous example:
     #
@@ -582,26 +685,26 @@ module ActiveRecord
     #
     # == Setting Inverses
     #
-    # If you are using a +belongs_to+ on the join model, it is a good idea to set the
-    # <tt>:inverse_of</tt> option on the +belongs_to+, which will mean that the following example
-    # works correctly (where <tt>tags</tt> is a +has_many+ <tt>:through</tt> association):
+    # If you are using a #belongs_to on the join model, it is a good idea to set the
+    # <tt>:inverse_of</tt> option on the #belongs_to, which will mean that the following example
+    # works correctly (where <tt>tags</tt> is a #has_many <tt>:through</tt> association):
     #
     #   @post = Post.first
     #   @tag = @post.tags.build name: "ruby"
     #   @tag.save
     #
-    # The last line ought to save the through record (a <tt>Taggable</tt>). This will only work if the
+    # The last line ought to save the through record (a <tt>Tagging</tt>). This will only work if the
     # <tt>:inverse_of</tt> is set:
     #
-    #   class Taggable < ActiveRecord::Base
+    #   class Tagging < ActiveRecord::Base
     #     belongs_to :post
     #     belongs_to :tag, inverse_of: :taggings
     #   end
     #
     # If you do not set the <tt>:inverse_of</tt> record, the association will
     # do its best to match itself up with the correct inverse. Automatic
-    # inverse detection only works on <tt>has_many</tt>, <tt>has_one</tt>, and
-    # <tt>belongs_to</tt> associations.
+    # inverse detection only works on #has_many, #has_one, and
+    # #belongs_to associations.
     #
     # Extra options on the associations, as defined in the
     # <tt>AssociationReflection::INVALID_AUTOMATIC_INVERSE_OPTIONS</tt> constant, will
@@ -614,7 +717,7 @@ module ActiveRecord
     # You can turn off the automatic detection of inverse associations by setting
     # the <tt>:inverse_of</tt> option to <tt>false</tt> like so:
     #
-    #   class Taggable < ActiveRecord::Base
+    #   class Tagging < ActiveRecord::Base
     #     belongs_to :tag, inverse_of: false
     #   end
     #
@@ -664,7 +767,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
@@ -748,7 +851,7 @@ module ActiveRecord
     #
     #   Post.includes(:author).each do |post|
     #
-    # This references the name of the +belongs_to+ association that also used the <tt>:author</tt>
+    # 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
     # all the referenced authors with one query. Doing so will cut down the number of queries
     # from 201 to 102.
@@ -759,7 +862,7 @@ module ActiveRecord
     #
     # This will load all comments with a single query. This reduces the total number of queries
     # to 3. In general, the number of queries will be 1 plus the number of associations
-    # named (except if some of the associations are polymorphic +belongs_to+ - see below).
+    # named (except if some of the associations are polymorphic #belongs_to - see below).
     #
     # To include a deep hierarchy of associations, use a hash:
     #
@@ -799,7 +902,7 @@ module ActiveRecord
     # In this case it is usually more natural to include an association which has conditions defined on it:
     #
     #   class Post < ActiveRecord::Base
-    #     has_many :approved_comments, -> { where approved: true }, class_name: 'Comment'
+    #     has_many :approved_comments, -> { where(approved: true) }, class_name: 'Comment'
     #   end
     #
     #   Post.includes(:approved_comments)
@@ -831,7 +934,7 @@ module ActiveRecord
     # For example if all the addressables are either of class Person or Company then a total
     # of 3 queries will be executed. The list of addressable types to load is determined on
     # the back of the addresses loaded. This is not supported if Active Record has to fallback
-    # to the previous implementation of eager loading and will raise <tt>ActiveRecord::EagerLoadPolymorphicError</tt>.
+    # to the previous implementation of eager loading and will raise ActiveRecord::EagerLoadPolymorphicError.
     # The reason is that the parent model's type is a column value so its corresponding table
     # name cannot be put in the +FROM+/+JOIN+ clauses of that query.
     #
@@ -873,7 +976,7 @@ module ActiveRecord
     #                              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 <tt>joins</tt> method, those table
+    # If you wish to specify your own custom joins using ActiveRecord::QueryMethods#joins method, those table
     # names will take precedence over the eager associations:
     #
     #   Post.joins(:comments).joins("inner join comments ...")
@@ -938,20 +1041,16 @@ 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,
-    # Active Record doesn't know anything about these inverse relationships and so no object
-    # loading optimization is possible. For example:
+    # Active Record can guess the inverse of the association based on the name
+    # of the class. The result is the following:
     #
     #    d = Dungeon.first
     #    t = d.traps.first
-    #    d.level == t.dungeon.level # => true
-    #    d.level = 10
-    #    d.level == t.dungeon.level # => false
+    #    d.object_id == t.dungeon.object_id # => true
     #
     # 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
-    # example, if we changed our model definitions to:
+    # the same in-memory instance since the association matches the name of the class.
+    # The result would be the same if we added +:inverse_of+ to our model definitions:
     #
     #    class Dungeon < ActiveRecord::Base
     #      has_many :traps, inverse_of: :dungeon
@@ -966,20 +1065,19 @@ module ActiveRecord
     #      belongs_to :dungeon, inverse_of: :evil_wizard
     #    end
     #
-    # Then, from our code snippet above, +d+ and <tt>t.dungeon</tt> are actually the same
-    # in-memory instance and our final <tt>d.level == t.dungeon.level</tt> will return +true+.
-    #
     # There are limitations to <tt>:inverse_of</tt> support:
     #
     # * does not work with <tt>:through</tt> associations.
     # * does not work with <tt>:polymorphic</tt> associations.
-    # * for +belongs_to+ associations +has_many+ inverse associations are ignored.
+    # * for #belongs_to associations #has_many inverse associations are ignored.
+    #
+    # For more information, see the documentation for the +:inverse_of+ option.
     #
     # == Deleting from associations
     #
     # === Dependent associations
     #
-    # +has_many+, +has_one+ and +belongs_to+ associations support the <tt>:dependent</tt> option.
+    # #has_many, #has_one and #belongs_to associations support the <tt>:dependent</tt> option.
     # This allows you to specify that associated records should be deleted when the owner is
     # deleted.
     #
@@ -1000,20 +1098,22 @@ module ActiveRecord
     # callbacks declared either before or after the <tt>:dependent</tt> option
     # can affect what it does.
     #
+    # Note that <tt>:dependent</tt> option is ignored for #has_one <tt>:through</tt> associations.
+    #
     # === Delete or destroy?
     #
-    # +has_many+ and +has_and_belongs_to_many+ associations have the methods <tt>destroy</tt>,
+    # #has_many and #has_and_belongs_to_many associations have the methods <tt>destroy</tt>,
     # <tt>delete</tt>, <tt>destroy_all</tt> and <tt>delete_all</tt>.
     #
-    # For +has_and_belongs_to_many+, <tt>delete</tt> and <tt>destroy</tt> are the same: they
+    # For #has_and_belongs_to_many, <tt>delete</tt> and <tt>destroy</tt> are the same: they
     # cause the records in the join table to be removed.
     #
-    # For +has_many+, <tt>destroy</tt> and <tt>destroy_all</tt> will always call the <tt>destroy</tt> method of the
+    # For #has_many, <tt>destroy</tt> and <tt>destroy_all</tt> will always call the <tt>destroy</tt> method of the
     # record(s) being removed so that callbacks are run. However <tt>delete</tt> and <tt>delete_all</tt> will either
     # do the deletion according to the strategy specified by the <tt>:dependent</tt> option, or
     # if no <tt>:dependent</tt> option is given, then it will follow the default strategy.
     # The default strategy is to do nothing (leave the foreign keys with the parent ids set), except for
-    # +has_many+ <tt>:through</tt>, where the default strategy is <tt>delete_all</tt> (delete
+    # #has_many <tt>:through</tt>, where the default strategy is <tt>delete_all</tt> (delete
     # the join records, without running their callbacks).
     #
     # There is also a <tt>clear</tt> method which is the same as <tt>delete_all</tt>, except that
@@ -1021,13 +1121,13 @@ module ActiveRecord
     #
     # === What gets deleted?
     #
-    # There is a potential pitfall here: +has_and_belongs_to_many+ and +has_many+ <tt>:through</tt>
+    # There is a potential pitfall here: #has_and_belongs_to_many and #has_many <tt>:through</tt>
     # associations have records in join tables, as well as the associated records. So when we
     # call one of these deletion methods, what exactly should be deleted?
     #
     # The answer is that it is assumed that deletion on an association is about removing the
     # <i>link</i> between the owner and the associated object(s), rather than necessarily the
-    # associated objects themselves. So with +has_and_belongs_to_many+ and +has_many+
+    # associated objects themselves. So with #has_and_belongs_to_many and #has_many
     # <tt>:through</tt>, the join records will be deleted, but the associated records won't.
     #
     # This makes sense if you think about it: if you were to call <tt>post.tags.delete(Tag.find_by(name: 'food'))</tt>
@@ -1038,20 +1138,20 @@ module ActiveRecord
     # a person has many projects, and each project has many tasks. If we deleted one of a person's
     # tasks, we would probably not want the project to be deleted. In this scenario, the delete method
     # won't actually work: it can only be used if the association on the join model is a
-    # +belongs_to+. In other situations you are expected to perform operations directly on
+    # #belongs_to. In other situations you are expected to perform operations directly on
     # either the associated records or the <tt>:through</tt> association.
     #
-    # With a regular +has_many+ there is no distinction between the "associated records"
+    # With a regular #has_many there is no distinction between the "associated records"
     # and the "link", so there is only one choice for what gets deleted.
     #
-    # With +has_and_belongs_to_many+ and +has_many+ <tt>:through</tt>, if you want to delete the
+    # With #has_and_belongs_to_many and #has_many <tt>:through</tt>, if you want to delete the
     # associated records themselves, you can always do something along the lines of
     # <tt>person.tasks.each(&:destroy)</tt>.
     #
-    # == Type safety with <tt>ActiveRecord::AssociationTypeMismatch</tt>
+    # == Type safety with ActiveRecord::AssociationTypeMismatch
     #
     # If you attempt to assign an object to an association that doesn't match the inferred
-    # or specified <tt>:class_name</tt>, you'll get an <tt>ActiveRecord::AssociationTypeMismatch</tt>.
+    # or specified <tt>:class_name</tt>, you'll get an ActiveRecord::AssociationTypeMismatch.
     #
     # == Options
     #
@@ -1064,13 +1164,14 @@ module ActiveRecord
       # +collection+ is a placeholder for the symbol passed as the +name+ argument, so
       # <tt>has_many :clients</tt> would add among others <tt>clients.empty?</tt>.
       #
-      # [collection(force_reload = false)]
-      #   Returns an array of all the associated objects.
-      #   An empty array is returned if none are found.
+      # [collection]
+      #   Returns a Relation of all the associated objects.
+      #   An empty Relation is returned if none are found.
       # [collection<<(object, ...)]
       #   Adds one or more objects to the collection by setting their foreign keys to the collection's primary key.
       #   Note that this operation instantly fires update SQL without waiting for the save or update call on the
       #   parent object, unless the parent object is a new record.
+      #   This will also run validations and callbacks of associated object(s).
       # [collection.delete(object, ...)]
       #   Removes one or more objects from the collection by setting their foreign keys to +NULL+.
       #   Objects will be in addition destroyed if they're associated with <tt>dependent: :destroy</tt>,
@@ -1088,7 +1189,8 @@ module ActiveRecord
       # [collection=objects]
       #   Replaces the collections content by deleting and adding objects as appropriate. If the <tt>:through</tt>
       #   option is true callbacks in the join models are triggered except destroy callbacks, since deletion is
-      #   direct.
+      #   direct by default. You can specify <tt>dependent: :destroy</tt> or
+      #   <tt>dependent: :nullify</tt> to override this.
       # [collection_singular_ids]
       #   Returns an array of the associated objects' ids
       # [collection_singular_ids=ids]
@@ -1105,10 +1207,10 @@ module ActiveRecord
       # [collection.size]
       #   Returns the number of associated objects.
       # [collection.find(...)]
-      #   Finds an associated object according to the same rules as <tt>ActiveRecord::Base.find</tt>.
+      #   Finds an associated object according to the same rules as ActiveRecord::FinderMethods#find.
       # [collection.exists?(...)]
       #   Checks whether an associated object with the given conditions exists.
-      #   Uses the same rules as <tt>ActiveRecord::Base.exists?</tt>.
+      #   Uses the same rules as ActiveRecord::FinderMethods#exists?.
       # [collection.build(attributes = {}, ...)]
       #   Returns one or more new objects of the collection type that have been instantiated
       #   with +attributes+ and linked to this object through a foreign key, but have not yet
@@ -1119,8 +1221,11 @@ module ActiveRecord
       #   been saved (if it passed the validation). *Note*: This only works if the base model
       #   already exists in the DB, not if it is a new (unsaved) record!
       # [collection.create!(attributes = {})]
-      #   Does the same as <tt>collection.create</tt>, but raises <tt>ActiveRecord::RecordInvalid</tt>
+      #   Does the same as <tt>collection.create</tt>, but raises ActiveRecord::RecordInvalid
       #   if the record is invalid.
+      # [collection.reload]
+      #   Returns a Relation of all of the associated objects, forcing a database read.
+      #   An empty Relation is returned if none are found.
       #
       # === Example
       #
@@ -1140,6 +1245,7 @@ module ActiveRecord
       # * <tt>Firm#clients.build</tt> (similar to <tt>Client.new("firm_id" => id)</tt>)
       # * <tt>Firm#clients.create</tt> (similar to <tt>c = Client.new("firm_id" => id); c.save; c</tt>)
       # * <tt>Firm#clients.create!</tt> (similar to <tt>c = Client.new("firm_id" => id); c.save!</tt>)
+      # * <tt>Firm#clients.reload</tt>
       # The declaration can also include an +options+ hash to specialize the behavior of the association.
       #
       # === Scopes
@@ -1171,11 +1277,11 @@ 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_many :products</tt> will by default be linked
-      #   to the Product class, but if the real class name is SpecialProduct, you'll have to
+      #   to the +Product+ class, but if the real class name is +SpecialProduct+, you'll have to
       #   specify it with this option.
       # [: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_many+
+      #   of this class in lower-case and "_id" suffixed. So a Person class that makes a #has_many
       #   association will use "person_id" as the default <tt>:foreign_key</tt>.
       # [:foreign_type]
       #   Specify the column used to store the associated object's type, if this is a polymorphic
@@ -1199,20 +1305,20 @@ module ActiveRecord
       #   * <tt>:restrict_with_error</tt> causes an error to be added to the owner if there are 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
+      #   a #belongs_to, and the records which get deleted are the join records, rather than
       #   the associated records.
       # [:counter_cache]
       #   This option can be used to configure a custom named <tt>:counter_cache.</tt> You only need this option,
-      #   when you customized the name of your <tt>:counter_cache</tt> on the <tt>belongs_to</tt> association.
+      #   when you customized the name of your <tt>:counter_cache</tt> on the #belongs_to association.
       # [:as]
-      #   Specifies a polymorphic interface (See <tt>belongs_to</tt>).
+      #   Specifies a polymorphic interface (See #belongs_to).
       # [:through]
       #   Specifies an association through which to perform the query. This can be any other type
       #   of association, including other <tt>:through</tt> associations. Options for <tt>:class_name</tt>,
       #   <tt>:primary_key</tt> and <tt>:foreign_key</tt> are ignored, as the association uses the
       #   source reflection.
       #
-      #   If the association on the join model is a +belongs_to+, the collection can be modified
+      #   If the association on the join model is a #belongs_to, the collection can be modified
       #   and the records on the <tt>:through</tt> model will be automatically created and removed
       #   as appropriate. Otherwise, the collection is read-only, so you should manipulate the
       #   <tt>:through</tt> association directly.
@@ -1223,15 +1329,16 @@ module ActiveRecord
       #   the appropriate join model records when they are saved. (See the 'Association Join Models'
       #   section above.)
       # [:source]
-      #   Specifies the source association name used by <tt>has_many :through</tt> queries.
+      #   Specifies the source association name used by #has_many <tt>:through</tt> queries.
       #   Only use it if the name cannot be inferred from the association.
       #   <tt>has_many :subscribers, through: :subscriptions</tt> will look for either <tt>:subscribers</tt> or
       #   <tt>:subscriber</tt> on Subscription, unless a <tt>:source</tt> is given.
       # [:source_type]
-      #   Specifies type of the source association used by <tt>has_many :through</tt> queries where the source
-      #   association is a polymorphic +belongs_to+.
+      #   Specifies type of the source association used by #has_many <tt>:through</tt> queries where the source
+      #   association is a polymorphic #belongs_to.
       # [:validate]
-      #   If +false+, don't validate the associated objects when saving the parent object. true by default.
+      #   When set to +true+, validates new objects added to association when saving the parent object. +true+ by default.
+      #   If you want to ensure associated objects are revalidated on every update, use +validates_associated+.
       # [:autosave]
       #   If true, always save the associated objects or destroy them if marked for destruction,
       #   when saving the parent object. If false, never save or destroy the associated objects.
@@ -1239,18 +1346,23 @@ module ActiveRecord
       #   +before_save+ callback. Because callbacks are run in the order they are defined, associated objects
       #   may need to be explicitly saved in any user-defined +before_save+ callbacks.
       #
-      #   Note that <tt>accepts_nested_attributes_for</tt> sets <tt>:autosave</tt> to <tt>true</tt>.
+      #   Note that NestedAttributes::ClassMethods#accepts_nested_attributes_for sets
+      #   <tt>:autosave</tt> to <tt>true</tt>.
       # [:inverse_of]
-      #   Specifies the name of the <tt>belongs_to</tt> association on the associated object
-      #   that is the inverse of this <tt>has_many</tt> association. Does not work in combination
+      #   Specifies the name of the #belongs_to association on the associated object
+      #   that is the inverse of this #has_many 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.
+      # [:extend]
+      #   Specifies a module or array of modules that will be extended into the association object returned.
+      #   Useful for defining methods on associations, especially when they should be shared between multiple
+      #   association objects.
       #
       # Option examples:
-      #   has_many :comments, -> { order "posted_on" }
-      #   has_many :comments, -> { includes :author }
+      #   has_many :comments, -> { order("posted_on") }
+      #   has_many :comments, -> { includes(:author) }
       #   has_many :people, -> { where(deleted: false).order("name") }, class_name: "Person"
-      #   has_many :tracks, -> { order "position" }, dependent: :destroy
+      #   has_many :tracks, -> { order("position") }, dependent: :destroy
       #   has_many :comments, dependent: :nullify
       #   has_many :tags, as: :taggable
       #   has_many :reports, -> { readonly }
@@ -1262,15 +1374,15 @@ module ActiveRecord
 
       # Specifies a one-to-one association with another class. This method should only be used
       # if the other class contains the foreign key. If the current class contains the foreign key,
-      # then you should use +belongs_to+ instead. See also ActiveRecord::Associations::ClassMethods's overview
-      # on when to use +has_one+ and when to use +belongs_to+.
+      # then you should use #belongs_to instead. See also ActiveRecord::Associations::ClassMethods's overview
+      # on when to use #has_one and when to use #belongs_to.
       #
       # The following methods for retrieval and query of a single associated object will be added:
       #
       # +association+ is a placeholder for the symbol passed as the +name+ argument, so
       # <tt>has_one :manager</tt> would add among others <tt>manager.nil?</tt>.
       #
-      # [association(force_reload = false)]
+      # [association]
       #   Returns the associated object. +nil+ is returned if none is found.
       # [association=(associate)]
       #   Assigns the associate object, extracts the primary key, sets it as the foreign key,
@@ -1285,8 +1397,10 @@ module ActiveRecord
       #   with +attributes+, linked to this object through a foreign key, and that
       #   has already been saved (if it passed the validation).
       # [create_association!(attributes = {})]
-      #   Does the same as <tt>create_association</tt>, but raises <tt>ActiveRecord::RecordInvalid</tt>
+      #   Does the same as <tt>create_association</tt>, but raises ActiveRecord::RecordInvalid
       #   if the record is invalid.
+      # [reload_association]
+      #   Returns the associated object, forcing a database read.
       #
       # === Example
       #
@@ -1296,6 +1410,7 @@ module ActiveRecord
       # * <tt>Account#build_beneficiary</tt> (similar to <tt>Beneficiary.new("account_id" => id)</tt>)
       # * <tt>Account#create_beneficiary</tt> (similar to <tt>b = Beneficiary.new("account_id" => id); b.save; b</tt>)
       # * <tt>Account#create_beneficiary!</tt> (similar to <tt>b = Beneficiary.new("account_id" => id); b.save!; b</tt>)
+      # * <tt>Account#reload_beneficiary</tt>
       #
       # === Scopes
       #
@@ -1326,9 +1441,11 @@ module ActiveRecord
       #   * <tt>:nullify</tt> causes the foreign key to be set to +NULL+. Callbacks are not executed.
       #   * <tt>:restrict_with_exception</tt> causes an exception to be raised if there is an associated record
       #   * <tt>:restrict_with_error</tt> causes an error to be added to the owner if there is an associated object
+      #
+      #   Note that <tt>:dependent</tt> option is ignored when using <tt>:through</tt> option.
       # [: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
+      #   of this class in lower-case and "_id" suffixed. So a Person class that makes a #has_one association
       #   will use "person_id" as the default <tt>:foreign_key</tt>.
       # [:foreign_type]
       #   Specify the column used to store the associated object's type, if this is a polymorphic
@@ -1339,31 +1456,33 @@ module ActiveRecord
       # [:primary_key]
       #   Specify the method that returns the primary key used for the association. By default this is +id+.
       # [:as]
-      #   Specifies a polymorphic interface (See <tt>belongs_to</tt>).
+      #   Specifies a polymorphic interface (See #belongs_to).
       # [:through]
       #   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.
+      #   source reflection. You can only use a <tt>:through</tt> query through a #has_one
+      #   or #belongs_to association on the join model.
       # [:source]
-      #   Specifies the source association name used by <tt>has_one :through</tt> queries.
+      #   Specifies the source association name used by #has_one <tt>:through</tt> queries.
       #   Only use it if the name cannot be inferred from the association.
       #   <tt>has_one :favorite, through: :favorites</tt> will look for a
       #   <tt>:favorite</tt> on Favorite, unless a <tt>:source</tt> is given.
       # [:source_type]
-      #   Specifies type of the source association used by <tt>has_one :through</tt> queries where the source
-      #   association is a polymorphic +belongs_to+.
+      #   Specifies type of the source association used by #has_one <tt>:through</tt> queries where the source
+      #   association is a polymorphic #belongs_to.
       # [:validate]
-      #   If +false+, don't validate the associated object when saving the parent object. +false+ by default.
+      #   When set to +true+, validates new objects added to association when saving the parent object. +false+ by default.
+      #   If you want to ensure associated objects are revalidated on every update, use +validates_associated+.
       # [:autosave]
       #   If true, always save the associated object or destroy it if marked for destruction,
       #   when saving the parent object. If false, never save or destroy the associated object.
       #   By default, only save the associated object if it's a new record.
       #
-      #   Note that <tt>accepts_nested_attributes_for</tt> sets <tt>:autosave</tt> to <tt>true</tt>.
+      #   Note that NestedAttributes::ClassMethods#accepts_nested_attributes_for sets
+      #   <tt>:autosave</tt> to <tt>true</tt>.
       # [: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
+      #   Specifies the name of the #belongs_to association on the associated object
+      #   that is the inverse of this #has_one 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.
       # [:required]
@@ -1375,12 +1494,12 @@ module ActiveRecord
       #   has_one :credit_card, dependent: :destroy  # destroys the associated credit card
       #   has_one :credit_card, dependent: :nullify  # updates the associated records foreign
       #                                                 # key value to NULL rather than destroying it
-      #   has_one :last_comment, -> { order 'posted_on' }, class_name: "Comment"
-      #   has_one :project_manager, -> { where role: 'project_manager' }, class_name: "Person"
+      #   has_one :last_comment, -> { order('posted_on') }, class_name: "Comment"
+      #   has_one :project_manager, -> { where(role: 'project_manager') }, class_name: "Person"
       #   has_one :attachment, as: :attachable
       #   has_one :boss, -> { readonly }
       #   has_one :club, through: :membership
-      #   has_one :primary_address, -> { where primary: true }, through: :addressables, source: :addressable
+      #   has_one :primary_address, -> { where(primary: true) }, through: :addressables, source: :addressable
       #   has_one :credit_card, required: true
       def has_one(name, scope = nil, options = {})
         reflection = Builder::HasOne.build(self, name, scope, options)
@@ -1389,8 +1508,8 @@ module ActiveRecord
 
       # Specifies a one-to-one association with another class. This method should only be used
       # if this class contains the foreign key. If the other class contains the foreign key,
-      # then you should use +has_one+ instead. See also ActiveRecord::Associations::ClassMethods's overview
-      # on when to use +has_one+ and when to use +belongs_to+.
+      # then you should use #has_one instead. See also ActiveRecord::Associations::ClassMethods's overview
+      # on when to use #has_one and when to use #belongs_to.
       #
       # Methods will be added for retrieval and query for a single associated object, for which
       # this object holds an id:
@@ -1398,7 +1517,7 @@ module ActiveRecord
       # +association+ is a placeholder for the symbol passed as the +name+ argument, so
       # <tt>belongs_to :author</tt> would add among others <tt>author.nil?</tt>.
       #
-      # [association(force_reload = false)]
+      # [association]
       #   Returns the associated object. +nil+ is returned if none is found.
       # [association=(associate)]
       #   Assigns the associate object, extracts the primary key, and sets it as the foreign key.
@@ -1410,8 +1529,10 @@ module ActiveRecord
       #   with +attributes+, linked to this object through a foreign key, and that
       #   has already been saved (if it passed the validation).
       # [create_association!(attributes = {})]
-      #   Does the same as <tt>create_association</tt>, but raises <tt>ActiveRecord::RecordInvalid</tt>
+      #   Does the same as <tt>create_association</tt>, but raises ActiveRecord::RecordInvalid
       #   if the record is invalid.
+      # [reload_association]
+      #   Returns the associated object, forcing a database read.
       #
       # === Example
       #
@@ -1421,6 +1542,7 @@ module ActiveRecord
       # * <tt>Post#build_author</tt> (similar to <tt>post.author = Author.new</tt>)
       # * <tt>Post#create_author</tt> (similar to <tt>post.author = Author.new; post.author.save; post.author</tt>)
       # * <tt>Post#create_author!</tt> (similar to <tt>post.author = Author.new; post.author.save!; post.author</tt>)
+      # * <tt>Post#reload_author</tt>
       # The declaration can also include an +options+ hash to specialize the behavior of the association.
       #
       # === Scopes
@@ -1430,7 +1552,7 @@ module ActiveRecord
       # when you access the associated object.
       #
       # Scope examples:
-      #   belongs_to :user, -> { where(id: 2) }
+      #   belongs_to :firm, -> { where(id: 2) }
       #   belongs_to :user, -> { joins(:friends) }
       #   belongs_to :level, ->(level) { where("game_level > ?", level.current) }
       #
@@ -1457,12 +1579,12 @@ module ActiveRecord
       # [:dependent]
       #   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.
-      #   This option should not be specified when <tt>belongs_to</tt> is used in conjunction with
-      #   a <tt>has_many</tt> relationship on another class because of the potential to leave
+      #   This option should not be specified when #belongs_to is used in conjunction with
+      #   a #has_many relationship on another class because of the potential to leave
       #   orphaned records behind.
       # [:counter_cache]
-      #   Caches the number of belonging objects on the associate class through the use of +increment_counter+
-      #   and +decrement_counter+. The counter cache is incremented when an object of this
+      #   Caches the number of belonging objects on the associate class through the use of CounterCache::ClassMethods#increment_counter
+      #   and CounterCache::ClassMethods#decrement_counter. The counter cache is incremented when an object of this
       #   class is created and decremented when it's destroyed. This requires that a column
       #   named <tt>#{table_name}_count</tt> (such as +comments_count+ for a belonging Comment class)
       #   is used on the associate class (such as a Post class) - that is the migration for
@@ -1477,27 +1599,35 @@ module ActiveRecord
       #   Note: If you've enabled the counter cache, then you may want to add the counter cache attribute
       #   to the +attr_readonly+ list in the associated classes (e.g. <tt>class Post; attr_readonly :comments_count; end</tt>).
       # [:validate]
-      #   If +false+, don't validate the associated objects when saving the parent object. +false+ by default.
+      #   When set to +true+, validates new objects added to association when saving the parent object. +false+ by default.
+      #   If you want to ensure associated objects are revalidated on every update, use +validates_associated+.
       # [:autosave]
       #   If true, always save the associated object or destroy it if marked for destruction, when
       #   saving the parent object.
       #   If false, never save or destroy the associated object.
       #   By default, only save the associated object if it's a new record.
       #
-      #   Note that <tt>accepts_nested_attributes_for</tt> sets <tt>:autosave</tt> to <tt>true</tt>.
+      #   Note that NestedAttributes::ClassMethods#accepts_nested_attributes_for
+      #   sets <tt>:autosave</tt> to <tt>true</tt>.
       # [:touch]
       #   If true, the associated object will be touched (the updated_at/on attributes set to current time)
       #   when this record is either saved or destroyed. If you specify a symbol, that attribute
       #   will be updated with the current time in addition to the updated_at/on attribute.
+      #   Please note that with touching no validation is performed and only the +after_touch+,
+      #   +after_commit+ and +after_rollback+ callbacks are executed.
       # [: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
+      #   Specifies the name of the #has_one or #has_many association on the associated
+      #   object that is the inverse of this #belongs_to 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.
+      # [:optional]
+      #   When set to +true+, the association will not have its presence validated.
       # [:required]
       #   When set to +true+, the association will also have its presence validated.
       #   This will validate the association itself, not the id. You can use
       #   +:inverse_of+ to avoid an extra query during validation.
+      #   NOTE: <tt>required</tt> is set to <tt>true</tt> by default and is deprecated. If
+      #   you don't want to have association presence validated, use <tt>optional: true</tt>.
       #
       # Option examples:
       #   belongs_to :firm, foreign_key: "client_of"
@@ -1508,9 +1638,9 @@ module ActiveRecord
       #   belongs_to :attachable, polymorphic: true
       #   belongs_to :project, -> { readonly }
       #   belongs_to :post, counter_cache: true
-      #   belongs_to :company, touch: true
+      #   belongs_to :comment, touch: true
       #   belongs_to :company, touch: :employees_last_updated_at
-      #   belongs_to :company, required: true
+      #   belongs_to :user, optional: true
       def belongs_to(name, scope = nil, options = {})
         reflection = Builder::BelongsTo.build(self, name, scope, options)
         Reflection.add_reflection self, name, reflection
@@ -1533,12 +1663,9 @@ module ActiveRecord
       # The join table should not have a primary key or a model associated with it. You must manually generate the
       # join table with a migration such as this:
       #
-      #   class CreateDevelopersProjectsJoinTable < ActiveRecord::Migration
+      #   class CreateDevelopersProjectsJoinTable < ActiveRecord::Migration[5.0]
       #     def change
-      #       create_table :developers_projects, id: false do |t|
-      #         t.integer :developer_id
-      #         t.integer :project_id
-      #       end
+      #       create_join_table :developers, :projects
       #     end
       #   end
       #
@@ -1551,9 +1678,9 @@ module ActiveRecord
       # +collection+ is a placeholder for the symbol passed as the +name+ argument, so
       # <tt>has_and_belongs_to_many :categories</tt> would add among others <tt>categories.empty?</tt>.
       #
-      # [collection(force_reload = false)]
-      #   Returns an array of all the associated objects.
-      #   An empty array is returned if none are found.
+      # [collection]
+      #   Returns a Relation of all the associated objects.
+      #   An empty Relation is returned if none are found.
       # [collection<<(object, ...)]
       #   Adds one or more objects to the collection by creating associations in the join table
       #   (<tt>collection.push</tt> and <tt>collection.concat</tt> are aliases to this method).
@@ -1580,10 +1707,10 @@ module ActiveRecord
       # [collection.find(id)]
       #   Finds an associated object responding to the +id+ and that
       #   meets the condition that it has to be associated with this object.
-      #   Uses the same rules as <tt>ActiveRecord::Base.find</tt>.
+      #   Uses the same rules as ActiveRecord::FinderMethods#find.
       # [collection.exists?(...)]
       #   Checks whether an associated object with the given conditions exists.
-      #   Uses the same rules as <tt>ActiveRecord::Base.exists?</tt>.
+      #   Uses the same rules as ActiveRecord::FinderMethods#exists?.
       # [collection.build(attributes = {})]
       #   Returns a new object of the collection type that has been instantiated
       #   with +attributes+ and linked to this object through the join table, but has not yet been saved.
@@ -1591,6 +1718,9 @@ module ActiveRecord
       #   Returns a new object of the collection type that has been instantiated
       #   with +attributes+, linked to this object through the join table, and that has already been
       #   saved (if it passed the validation).
+      # [collection.reload]
+      #   Returns a Relation of all of the associated objects, forcing a database read.
+      #   An empty Relation is returned if none are found.
       #
       # === Example
       #
@@ -1609,6 +1739,7 @@ module ActiveRecord
       # * <tt>Developer#projects.exists?(...)</tt>
       # * <tt>Developer#projects.build</tt> (similar to <tt>Project.new("developer_id" => id)</tt>)
       # * <tt>Developer#projects.create</tt> (similar to <tt>c = Project.new("developer_id" => id); c.save; c</tt>)
+      # * <tt>Developer#projects.reload</tt>
       # The declaration may include an +options+ hash to specialize the behavior of the association.
       #
       # === Scopes
@@ -1618,7 +1749,7 @@ module ActiveRecord
       # query when you access the associated collection.
       #
       # Scope examples:
-      #   has_and_belongs_to_many :projects, -> { includes :milestones, :manager }
+      #   has_and_belongs_to_many :projects, -> { includes(:milestones, :manager) }
       #   has_and_belongs_to_many :categories, ->(category) {
       #     where("default_category = ?", category.name)
       #   }
@@ -1647,32 +1778,32 @@ module ActiveRecord
       # [:join_table]
       #   Specify the name of the join table if the default based on lexical order isn't what you want.
       #   <b>WARNING:</b> If you're overwriting the table name of either class, the +table_name+ method
-      #   MUST be declared underneath any +has_and_belongs_to_many+ declaration in order to work.
+      #   MUST be declared underneath any #has_and_belongs_to_many declaration in order to work.
       # [: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_and_belongs_to_many+ association to Project will use "person_id" as the
+      #   a #has_and_belongs_to_many association to Project will use "person_id" as the
       #   default <tt>:foreign_key</tt>.
       # [:association_foreign_key]
       #   Specify the foreign key used for the association on the receiving side of the association.
       #   By default this is guessed to be the name of the associated class in lower-case and "_id" suffixed.
-      #   So if a Person class makes a +has_and_belongs_to_many+ association to Project,
+      #   So if a Person class makes a #has_and_belongs_to_many association to Project,
       #   the association will use "project_id" as the default <tt>:association_foreign_key</tt>.
-      # [:readonly]
-      #   If true, all the associated objects are readonly through the association.
       # [:validate]
-      #   If +false+, don't validate the associated objects when saving the parent object. +true+ by default.
+      #   When set to +true+, validates new objects added to association when saving the parent object. +true+ by default.
+      #   If you want to ensure associated objects are revalidated on every update, use +validates_associated+.
       # [:autosave]
       #   If true, always save the associated objects or destroy them if marked for destruction, when
       #   saving the parent object.
       #   If false, never save or destroy the associated objects.
       #   By default, only save associated objects that are new records.
       #
-      #   Note that <tt>accepts_nested_attributes_for</tt> sets <tt>:autosave</tt> to <tt>true</tt>.
+      #   Note that NestedAttributes::ClassMethods#accepts_nested_attributes_for sets
+      #   <tt>:autosave</tt> to <tt>true</tt>.
       #
       # Option examples:
       #   has_and_belongs_to_many :projects
-      #   has_and_belongs_to_many :projects, -> { includes :milestones, :manager }
+      #   has_and_belongs_to_many :projects, -> { includes(:milestones, :manager) }
       #   has_and_belongs_to_many :nations, class_name: "Country"
       #   has_and_belongs_to_many :categories, join_table: "prods_cats"
       #   has_and_belongs_to_many :categories, -> { readonly }
@@ -1688,16 +1819,14 @@ module ActiveRecord
 
         join_model = builder.through_model
 
-        # FIXME: we should move this to the internal constants. Also people
-        # should never directly access this constant so I'm not happy about
-        # setting it.
         const_set join_model.name, join_model
+        private_constant join_model.name
 
         middle_reflection = builder.middle_reflection join_model
 
         Builder::HasMany.define_callbacks self, middle_reflection
         Reflection.add_reflection self, middle_reflection.name, middle_reflection
-        middle_reflection.parent_reflection = [name.to_s, habtm_reflection]
+        middle_reflection.parent_reflection = habtm_reflection
 
         include Module.new {
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
@@ -1718,7 +1847,7 @@ module ActiveRecord
         end
 
         has_many name, scope, hm_options, &extension
-        self._reflections[name.to_s].parent_reflection = [name.to_s, habtm_reflection]
+        self._reflections[name.to_s].parent_reflection = habtm_reflection
       end
     end
   end