1 files changed, 21 insertions, 14 deletions
diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 1ca648d48d..a830b0e0e4 100644
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -61,12 +61,18 @@ module ActiveRecord
     end
   end
 
-  class HasManyThroughCantAssociateThroughHasOneOrManyReflection < ActiveRecordError #:nodoc:
+  class ThroughCantAssociateThroughHasOneOrManyReflection < 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}.")
     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.")
@@ -79,12 +85,18 @@ module ActiveRecord
     end
   end
 
-  class HasManyThroughNestedAssociationsAreReadonly < ActiveRecordError #:nodoc:
+  class ThroughNestedAssociationsAreReadonly < 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
   end
 
+  class HasManyThroughNestedAssociationsAreReadonly < ThroughNestedAssociationsAreReadonly #:nodoc:
+  end
+
+  class HasOneThroughNestedAssociationsAreReadonly < ThroughNestedAssociationsAreReadonly #:nodoc:
+  end
+
   class EagerLoadPolymorphicError < ActiveRecordError #:nodoc:
     def initialize(reflection)
       super("Cannot eagerly load the polymorphic association #{reflection.name.inspect}")
@@ -955,20 +967,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
@@ -983,15 +991,14 @@ 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 more information, see the documentation for the +:inverse_of+ option.
+    #
     # == Deleting from associations
     #
     # === Dependent associations