Getting rid of the +automatic_inverse_of: false+ option in associations in favor

of using +inverse_of: false+ option. Changing the documentation and
adding a CHANGELOG entry for the automatic inverse detection feature.

5 files changed, 19 insertions, 14 deletions

diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 3490057298..6fd4f3042c 100644
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -586,9 +586,10 @@ module ActiveRecord
     #     belongs_to :tag, inverse_of: :taggings
     #   end
     #
-    # If you do not set the +:inverse_of+ record, the association will do its
-    # best to match itself up with the correct inverse. Automatic +:inverse_of+
-    # detection only works on +has_many+, +has_one+, and +belongs_to+ associations.
+    # 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.
     #
     # Extra options on the associations, as defined in the
     # <tt>AssociationReflection::INVALID_AUTOMATIC_INVERSE_OPTIONS</tt> constant, will
@@ -599,10 +600,10 @@ module ActiveRecord
     # especially the ones with non-standard names.
     #
     # You can turn off the automatic detection of inverse associations by setting
-    # the +:automatic_inverse_of+ option to +false+ like so:
+    # the <tt>:inverse_of</tt> option to <tt>false</tt> like so:
     #
     #   class Taggable < ActiveRecord::Base
-    #     belongs_to :tag, automatic_inverse_of: false
+    #     belongs_to :tag, inverse_of: false
     #   end
     #
     # == Nested \Associations
diff --git a/activerecord/lib/active_record/associations/builder/has_many.rb b/activerecord/lib/active_record/associations/builder/has_many.rb
index 429def5455..0d1bdd21ee 100644
--- a/activerecord/lib/active_record/associations/builder/has_many.rb
+++ b/activerecord/lib/active_record/associations/builder/has_many.rb
@@ -5,7 +5,7 @@ module ActiveRecord::Associations::Builder
     end
 
     def valid_options
-      super + [:primary_key, :dependent, :as, :through, :source, :source_type, :inverse_of, :automatic_inverse_of, :counter_cache]
+      super + [:primary_key, :dependent, :as, :through, :source, :source_type, :inverse_of, :counter_cache]
     end
 
     def valid_dependent_options
diff --git a/activerecord/lib/active_record/associations/builder/singular_association.rb b/activerecord/lib/active_record/associations/builder/singular_association.rb
index 96ccbeb8a3..76e48e66e5 100644
--- a/activerecord/lib/active_record/associations/builder/singular_association.rb
+++ b/activerecord/lib/active_record/associations/builder/singular_association.rb
@@ -3,7 +3,7 @@
 module ActiveRecord::Associations::Builder
   class SingularAssociation < Association #:nodoc:
     def valid_options
-      super + [:remote, :dependent, :counter_cache, :primary_key, :inverse_of, :automatic_inverse_of]
+      super + [:remote, :dependent, :counter_cache, :primary_key, :inverse_of]
     end
 
     def constructable?
diff --git a/activerecord/lib/active_record/nested_attributes.rb b/activerecord/lib/active_record/nested_attributes.rb
index 8bdaeef924..0e8822d63f 100644
--- a/activerecord/lib/active_record/nested_attributes.rb
+++ b/activerecord/lib/active_record/nested_attributes.rb
@@ -230,6 +230,10 @@ module ActiveRecord
     #     validates_presence_of :member
     #   end
     #
+    # Note that if you do not specify the <tt>inverse_of</tt> option, then
+    # Active Record will try to automatically guess the inverse association
+    # based on heuristics.
+    #
     # For one-to-one nested associations, if you build the new (in-memory)
     # child object yourself before assignment, then this module will not
     # overwrite it, e.g.:
diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb
index 27aa20b6c0..2ba89b13b7 100644
--- a/activerecord/lib/active_record/reflection.rb
+++ b/activerecord/lib/active_record/reflection.rb
@@ -313,8 +313,7 @@ module ActiveRecord
       # and prevents this object from finding the inverse association
       # automatically in the future.
       def remove_automatic_inverse_of!
-        @automatic_inverse_of = nil
-        options[:automatic_inverse_of] = false
+        @automatic_inverse_of = false
       end
 
       def polymorphic_inverse_of(associated_class)
@@ -449,15 +448,16 @@ module ActiveRecord
 
         # Checks to see if the reflection doesn't have any options that prevent
         # us from being able to guess the inverse automatically. First, the
-        # +automatic_inverse_of+ option cannot be set to false. Second, we must
-        # have +has_many+, +has_one+, +belongs_to+ associations. Third, we must
-        # not have options such as +:polymorphic+ or +:foreign_key+ which prevent us
-        # from correctly guessing the inverse association.
+        # <tt>inverse_of</tt> option cannot be set to false. Second, we must
+        # have <tt>has_many</tt>, <tt>has_one</tt>, <tt>belongs_to</tt> associations.
+        # Third, we must not have options such as <tt>:polymorphic</tt> or
+        # <tt>:foreign_key</tt> which prevent us from correctly guessing the
+        # inverse association.
         #
         # Anything with a scope can additionally ruin our attempt at finding an
         # inverse, so we exclude reflections with scopes.
         def can_find_inverse_of_automatically?(reflection)
-          reflection.options[:automatic_inverse_of] != false &&
+          reflection.options[:inverse_of] != false &&
             VALID_AUTOMATIC_INVERSE_MACROS.include?(reflection.macro) &&
             !INVALID_AUTOMATIC_INVERSE_OPTIONS.any? { |opt| reflection.options[opt] } &&
             !reflection.scope