Clarified the difference between `:foreign_key` and `:association_foreign_key` options in HABTM association

1 files changed, 7 insertions, 5 deletions

diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 8b51a38f48..425d71ecc1 100755
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -1149,13 +1149,15 @@ module ActiveRecord
       #   <b>WARNING:</b> If you're overwriting the table name of either class, the +table_name+ method
       #   MUST be declared underneath any +has_and_belongs_to_many+ declaration in order to work.
       # [:foreign_key]
-      #   Specify the foreign key used for the association. By default this is guessed to be the name
-      #   of this class in lower-case and "_id" suffixed. So a Person class that makes a +has_and_belongs_to_many+ association
+      #   Specify the foreign key used for the association (on "this side" of association).
+      #   By default this is guessed to be the name of this class in lower-case and "_id" suffixed.
+      #   So a Person class that makes a +has_and_belongs_to_many+ association to Project
       #   will use "person_id" as the default <tt>:foreign_key</tt>.
       # [:association_foreign_key]
-      #   Specify the association foreign key used for the association. By default this is
-      #   guessed to be the name of the associated class in lower-case and "_id" suffixed. So if the associated class is Project,
-      #   the +has_and_belongs_to_many+ association will use "project_id" as the default <tt>:association_foreign_key</tt>.
+      #   Specify the association foreign key used for the association (on the "other side" of association). 
+      #   By default this is guessed to be the name of the associated class in lower-case and "_id" suffixed.
+      #   So if a Person class makes a +has_and_belongs_to_many+ association to Project,
+      #   the association will use "project_id" as the default <tt>:association_foreign_key</tt>.
       # [:conditions]
       #   Specify the conditions that the associated object must meet in order to be included as a +WHERE+
       #   SQL fragment, such as <tt>authorized = 1</tt>.  Record creations from the association are scoped if a hash is used.