Adding documentation to the automatic inverse_of finder.

activerecord/lib/active_record/associations.rb

@@ -568,6 +568,8 @@ def association_instance_set(name, association)
     #   @group.avatars << Avatar.new   # this would work if User belonged_to Avatar rather than the other way around
     #   @group.avatars.delete(@group.avatars.last)  # so would this
     #
+    # == 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):
@@ -584,6 +586,25 @@ def association_instance_set(name, association)
     #     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.
+    #
+    # Extra options on the associations, as defined in the
+    # +AssociationReflection::INVALID_AUTOMATIC_INVERSE_OPTIONS+ constant, will
+    # also prevent the association's inverse from being found automatically.
+    #
+    # The automatic guessing of the inverse association uses a heuristic based
+    # on the name of the class, so it may not work for all associations,
+    # 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:
+    #
+    #   class Taggable < ActiveRecord::Base
+    #     belongs_to :tag, automatic_inverse_of: false
+    #   end
+    #
     # == Nested Associations
     #
     # You can actually specify *any* association with the <tt>:through</tt> option, including an

activerecord/lib/active_record/reflection.rb

@@ -450,7 +450,7 @@ def valid_inverse_reflection?(reflection)
         # 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 :class_name or :polymorphic which prevent us
+        # not have options such as :polymorphic or :foreign_key which prevent us
         # from correctly guessing the inverse association.
         #
         # Anything with a scope can additionally ruin our attempt at finding an

guides/source/association_basics.md

@@ -693,6 +693,17 @@ There are a few limitations to `inverse_of` support:
 * They do not work with `:as` associations.
 * For `belongs_to` associations, `has_many` inverse associations are ignored.
 
+Every association will attempt to automatically find the inverse association
+and set the `:inverse_of` option heuristically (based on the association name).
+Most associations with standard names will be supported. However, associations
+that contain the following options will not have their inverses set
+automatically:
+
+* :conditions
+* :through
+* :polymorphic
+* :foreign_key
+
 Detailed Association Reference
 ------------------------------