From 346cda4f348993b45a894c1351e2cca03d72dee2 Mon Sep 17 00:00:00 2001 From: wangjohn Date: Sat, 11 May 2013 22:56:05 -0400 Subject: [PATCH] Adding documentation to the automatic inverse_of finder. --- .../lib/active_record/associations.rb | 21 +++++++++++++++++++ activerecord/lib/active_record/reflection.rb | 2 +- guides/source/association_basics.md | 11 ++++++++++ 3 files changed, 33 insertions(+), 1 deletion(-) diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 5e5995f566..b71200cd2a 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -568,6 +568,8 @@ module ActiveRecord # @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 # :inverse_of option on the +belongs_to+, which will mean that the following example # works correctly (where tags is a +has_many+ :through association): @@ -584,6 +586,25 @@ 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. + # + # 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 :through option, including an diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb index 0ba860a186..d922e23e39 100644 --- a/activerecord/lib/active_record/reflection.rb +++ b/activerecord/lib/active_record/reflection.rb @@ -450,7 +450,7 @@ module ActiveRecord # 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 diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md index 8d203d265a..16a5241319 100644 --- a/guides/source/association_basics.md +++ b/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 ------------------------------