Docs: warn that associations names shouldn't be reserved words. Closes #4378.

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@6770 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

activerecord/CHANGELOG

 *SVN*
 
+* Docs: warn that associations names shouldn't be reserved words.  #4378 [murphy@cYcnus.de, Josh Susser]
+
 * Sanitize Base#inspect.  #8392 [Nik Wakelin]
 
 * Replace the transaction {|transaction|..} semantics with a new Exception ActiveRecord::Rollback.   [Koz]

activerecord/lib/active_record/associations.rb

@@ -95,6 +95,12 @@ def clear_association_cache #:nodoc:
     # * <tt>Project#categories.empty?, Project#categories.size, Project#categories, Project#categories<<(category1),</tt>
     #   <tt>Project#categories.delete(category1)</tt>
     #
+    # === A word of warning
+    #
+    # Don't create associations that have the same name as instance methods of ActiveRecord::Base. Since the association
+    # adds a method with that name to its model, it will override the inherited method and break things.
+    # For instance, #attributes and #connection would be bad choices for association names.
+    #
     # == Example
     #
     # link:files/examples/associations.png