1 files changed, 24 insertions, 9 deletions
diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 19308643f3..1db5fc0dd1 100644
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -107,6 +107,21 @@ module ActiveRecord
     end
   end
 
+  class AmbiguousSourceReflectionForThroughAssociation < ActiveRecordError # :nodoc:
+    def initialize(klass, macro, association_name, options, possible_sources)
+      example_options = options.dup
+      example_options[:source] = possible_sources.first
+
+      super("Ambiguous source reflection for through association. Please " \
+            "specify a :source directive on your declaration like:\n" \
+            "\n" \
+            "  class #{klass} < ActiveRecord::Base\n" \
+            "    #{macro} :#{association_name}, #{example_options}\n" \
+            "  end"
+           )
+    end
+  end
+
   class HasManyThroughCantAssociateThroughHasOneOrManyReflection < ThroughCantAssociateThroughHasOneOrManyReflection #:nodoc:
   end
 
@@ -260,11 +275,11 @@ module ActiveRecord
 
     private
       # Clears out the association cache.
-      def clear_association_cache # :nodoc:
+      def clear_association_cache
         @association_cache.clear if persisted?
       end
 
-      def init_internals # :nodoc:
+      def init_internals
         @association_cache = {}
         super
       end
@@ -354,23 +369,23 @@ module ActiveRecord
       #
       # === Overriding generated methods
       #
-      # Association methods are generated in a module that is included into the model class,
-      # which allows you to easily override with your own methods and call the original
-      # generated method with +super+. For example:
+      # Association methods are generated in a module included into the model
+      # class, making overrides easy. The original generated method can thus be
+      # called with +super+:
       #
       #   class Car < ActiveRecord::Base
       #     belongs_to :owner
       #     belongs_to :old_owner
+      #
       #     def owner=(new_owner)
       #       self.old_owner = self.owner
       #       super
       #     end
       #   end
       #
-      # If your model class is <tt>Project</tt>, then the module is
-      # named <tt>Project::GeneratedAssociationMethods</tt>. The +GeneratedAssociationMethods+ module is
-      # included in the model class immediately after the (anonymous) generated attributes methods
-      # module, meaning an association will override the methods for an attribute with the same name.
+      # The association methods module is included immediately after the
+      # generated attributes methods module, meaning an association will
+      # override the methods for an attribute with the same name.
       #
       # == Cardinality and associations
       #