Permalink
Browse files

Merge pull request #10574 from wangjohn/automatic_inverse_of_document…

…ation

Adding documentation to the automatic inverse_of finder.
  • Loading branch information...
2 parents d9e8ec6 + 346cda4 commit 98ade30e421e2c9e405060bba87ecbd092f11698 @rafaelfranca rafaelfranca committed May 12, 2013
@@ -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
@@ -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
@@ -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
------------------------------

0 comments on commit 98ade30

Please sign in to comment.