Merge pull request #20542 from repinel/fix-bi-directional-assoc-doc

[ci skip] Fix the API docs for Bi-directional associations

1 files changed, 7 insertions, 12 deletions

diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 1ca648d48d..82cb3fed59 100644
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -955,20 +955,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 +979,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