Merge pull request #22240 from resource11/resource11-patch-1

Requesting documentation update

activerecord/lib/active_record/associations.rb

@@ -300,10 +300,10 @@ def association_instance_set(name, association)
     #
     # === 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.
+    # Don't create associations that have the same name as [instance methods](http://api.rubyonrails.org/classes/ActiveRecord/Core.html) of
+    # <tt>ActiveRecord::Base</tt>. Since the association adds a method with that name to
+    # its model, using an association with the same name as one provided by <tt>ActiveRecord::Base</tt> will override the method inherited through <tt>ActiveRecord::Base</tt> and will break things.
+    # For instance, +attributes+ and +connection+ would be bad choices for association names, because those names already exist in the list of <tt>ActiveRecord::Base</tt> instance methods.
     #
     # == Auto-generated methods
     # See also Instance Public methods below for more details.